affinity

Affinity Control

Affinity（/Applications/Affinity.app、Canva 時代の統合アプリ）には、AppleScript の 辞書も CLI も URL スキームもなく、ファイル形式は独自仕様です。唯一の自動化手段は AI connector です。有効にすると、アプリは JavaScript スクリプティング SDK を http://localhost:6767/sse で提供します。このエンドポイントは MCP プロトコルを使用しますが、このスキルは依存関係ゼロの Node CLI を使い、HTTP/SSE 経由で直接操作します。MCP クライアントの設定も、ツールスキーマのコンテキストへの読み込みも必要ありません。Affinity 3.3.0（build 4850）でエンドツーエンドの動作を確認済みです。

• scripts/affinity-cli.mjs — CLI（Node ≥ 18、npm install 不要）。
• references/api-reference.md — 確認済みのエンドポイントツールの仕様と SDK プリアンブルの要約。スクリプトを書く前に読んでください。
• references/sdk-map.md — 厳選した SDK の要約：モジュールマップ、ノードモデル、作成手順（テキスト、画像、調整）、注意点。基本的な描画手順を超える内容を書く場合に読んでください。
• references/sdk-docs/ — SDK ドキュメント全体（ベンダー提供版、142 トピック、約 1.8 MB）。正確なシグネチャを検索する場合に限り、sdk-map.md を読んだ後で grep してください。大きなファイル全体は読まないでください（nodes.js は約 300 KB です）。
• ベンダー提供の JS がラップするネイティブな *Api 層のオンラインシグネチャリファレンス： https://sdk.affinity.studio/latest/js/（apis/<ApiName>/<method>.html、enums/<Enum>.html）。

制御ループ

1. 事前確認 — エンドポイントはリモートから有効化できません。

   node scripts/affinity-cli.mjs ping     # → "OK http://localhost:6767 — Affinity 1.0.0"
   

   失敗した場合は、Affinity を起動して AI connector を有効にするようユーザーに依頼してください （Affinity Settings → AI connector。セットアップガイド を参照してください。そこにある Claude 側のコネクター手順は不要で、アプリ内の切り替えだけが必要です）。

2. スクリプトを書く — Affinity SDK を使った JavaScript です。 references/api-reference.md から始め、適切なモジュールと手順については references/sdk-map.md を参照してください。 正確なシグネチャは references/sdk-docs/ を grep してください。スクリプトはトップレベルで実行されるコードです。出力は console.log() からのみ行ってください （戻り値は破棄されます）。エントリーポイント：

   const { app } = require('/application');   // '/application.js' works too
   const doc = app.documents.current;          // null when no document is open
   

   最初のスクリプトではほぼ必ずつまずく点が 3 つあります。最初に正しく設定してください。

   • 新規ドキュメントのデフォルト単位はミリメートルです。 NewDocumentOptions のセッターは書き込み専用です。o.width/height/dpi を設定する前に、/units.js の UnitType.Pixel を使って o.units = UnitType.Pixel と設定してください。
   • テキストサイズの単位はポイントではなくドキュメントピクセルです： px = pt * doc.dpi / 72。
   • app.documents.all は通常の Array ですが、ノードの .children は遅延読み込みの Collection です — sdk-map を参照してください。

   ユーザーの設定で何が許可されているかわからない場合は、それらを必要とするコードを書く前に require('/environment').Environment.permissions （→ {fileSystem, network, genAI}）と .fileSystemRoots をログに出力してください。

   API の扱いに困ったときは、コミュニティが投稿したヒントのプールを検索してください。 node scripts/affinity-cli.mjs search "set blend mode"。

3. 実行：

   node scripts/affinity-cli.mjs run myscript.js
   

   エンドポイントの execute_script 経由で実行し、スクリプトのコンソール出力を表示します。 エラーはテキストで返されるため、ファイルを修正して再実行してください。

4. 見た目を確認する — スクリプトが動作したと決めつけないでください。

   node scripts/affinity-cli.mjs render --out /tmp/check.jpg            # current spread
   node scripts/affinity-cli.mjs render --selection --out /tmp/sel.jpg  # selection only
   

   次に JPEG を Read します（最大 1024 px）。ドキュメントセッションの uuid は自動的に取得されます。

5. 登録する — ユーザーがスクリプトに納得したら、再利用できるようにインストールします。

   node scripts/affinity-cli.mjs add --title "My Script" --description "What it does" --file myscript.js
   

   ライブラリスクリプトは Affinity の Window → General → Scripts に表示されます。

CLI チートシート

node scripts/affinity-cli.mjs ping                          # endpoint alive?
node scripts/affinity-cli.mjs run file.js                   # execute script, print console output
node scripts/affinity-cli.mjs run -                       # same, script read from stdin (heredoc)
node scripts/affinity-cli.mjs render [--selection] [--spread N] --out f.jpg
node scripts/affinity-cli.mjs tools [--json]                # list endpoint tools (verified list in api-reference)
node scripts/affinity-cli.mjs call <tool> '{"arg":"val"}'   # generic tool call
node scripts/affinity-cli.mjs add --title "T" --description "D" --file f.js
node scripts/affinity-cli.mjs list                          # library scripts
node scripts/affinity-cli.mjs save --title "T" --out f.js   # export library script to disk
node scripts/affinity-cli.mjs search "query"                # SDK hints search
node scripts/affinity-cli.mjs docs [<topic>]                # list / print SDK doc topics
node scripts/affinity-cli.mjs docs-dump <dir> [--force]     # (re-)vendor SDK docs; resumable

環境変数による上書き：AFFINITY_MCP_URL（デフォルトは http://localhost:6767）、AFFINITY_TIMEOUT_MS （デフォルトは 120000。長時間のバッチスクリプトでは値を大きくしてください）。

既知の制限事項

• PERMISSION_DENIED エラー（SDK の前置きでは NOT_ALLOWED と呼ばれます）は、ユーザーが Affinity の設定でスクリプトによる AI／ファイルシステム／ネットワークへのアクセスを無効にしていることを意味します。必要な設定を有効にするよう依頼してください。回避策を探ってはいけません。
• スクリプトからのファイルシステムアクセスはデスクトップのみ（app.userDesktopPath）です。スクリプトコードからネットワークにはアクセスできません。確認には、スクリプト側でのエクスポートより render を優先してください。
• ライブラリスクリプトはエンドポイント経由で削除できません。削除できるのは Scripts パネルからのみです。
• 現在の見開きを設定すると選択が解除されます。実際に切り替える場合にのみ設定してください。
• doc.close() は確認を表示せず、未保存の変更を破棄して閉じます。スクリプト自身が作成したドキュメントのみ閉じるか、先に save() を実行してください。
• 長時間のバッチ処理中にエンドポイントのセッションが切れることがあります（POST → HTTP 404）。その場合は再実行してください。CLI を実行するたびに新しいセッションが開始されます（前置きのゲート処理は自動で行われます）。
• Affinity のアップデート後は、app.version が上記のバージョンと一致するか確認してください。バージョンが変わっていた場合は、空のディレクトリにダンプし（docs-dump /tmp/sdk-new を実行してから references/sdk-docs/ を置き換えます）、api-reference と sdk-map のダイジェストを更新してください。古いツリーに上書きすると、古いファイルが残り、変更されたファイルがスキップされます。
• エンドポイントのルートが利用できない場合の代替手段として、macOS の GUI オートメーション（System Events によるキー入力／メニュー操作）は機能しますが、壊れやすく、検証もできません。単発の簡単な操作に限って使用し、ドキュメントの編集には決して使用しないでください。

セキュリティ

ほかのアプリオートメーションスキルとは異なり、このスキルは独自のポートを開きません。リスナーは Affinity のものです。ただし、AI コネクターを有効にするかどうかは、明示的に検討すべき判断です。

• コネクターを有効にすると、Affinity はスクリプト SDK 全体を http://localhost:6767/sse で公開します。このエンドポイントは、ユーザーが開いているドキュメントに対して JavaScript を実行します。affinity-cli.mjs はこのエンドポイントのクライアントにすぎません。
• エンドポイントには認証がありません。有効になっている間は、すべてのローカルプロセスと、共有マシン上のほかのすべてのユーザーが、このエンドポイントを介して Affinity を操作できます。CLI は、AFFINITY_MCP_URL のオリジンから外部へリダイレクトする SSE エンドポイントを拒否するため、セッションを乗っ取られても接続先がひそかに変更されることはありません。ただし、保護されるのはこのクライアントであり、エンドポイントではありません。
• スクリプトがアクセスできる範囲は、Affinity 独自の AI／ファイルシステム／ネットワークのスイッチで制限されます（PERMISSION_DENIED エラーは、そのいずれかがオフになっていることを意味します）。スイッチをオンにすると、このスキルだけでなく、あらゆるクライアントが実行できる操作の範囲が広がります。推測で決めず、確認してください。
• 無効にするには、Affinity の設定で AI コネクターをオフにしてください。 エンドポイントも同時に停止します。このスキルがインストールしたもので、リスニングを続けるものはありません。