マクロ（操作の自動化）¶

Zenith Filer は、よく行う操作を自動化できる「マクロ」機能を備えています。マクロは内部的には JavaScript で記述されますが、コードを書かなくても部品（ブロック）を線でつないで組み立てるマクロスタジオや、実際の操作を覚えさせる記録から作れるため、はじめての方でも利用できます。作成・編集は常にマクロスタジオで行い、ナビペインの「マクロ」ビューは保存済みマクロの一覧・実行に専念します。

マクロの入口¶

マクロは次の場所から利用できます。

ナビペインの「マクロ」ビュー: お気に入りやツリーなどと並ぶ常設ビューです（アイコンは稲妻 ⚡）。保存済みマクロの一覧が表示され、各項目には名前・設定済みトリガーのバッジ・▶ 実行ボタンが並びます。ダブルクリックで実行、右クリックで「実行／スタジオで編集／複製／削除」を選べます。ヘッダーの「＋」でマクロスタジオを新規マクロ状態で開けます。
ステータスバー右側の 2 アイコン: すばやくマクロを呼び出すためのボタンです。
⏺（記録）: 操作の記録を開始・停止します。
⚡（保存マクロ）: 保存済みマクロのプルダウンを開き、クリックでそのまま実行します。「＋新規マクロ」からマクロスタジオを開いたり、各項目の右クリックから「スタジオで編集」できます。
マクロスタジオ: 作成・編集を行う独立ウィンドウです（詳細は マクロスタジオ）。

実行の仕組み（zen.* API）¶

マクロは内部で zen.* という専用 API を使ってアプリの操作を記述します。主な API は次のとおりです。

フォルダ移動（navigate）/ 検索（search）
フォルダ作成（createFolder）/ 移動（move）/ リネーム（rename）/ コピー（copy）/ 削除（delete・ゴミ箱へ送ります）
通知（notify）/ ログ出力（log）
実行時の問い合わせ（confirm はい/いいえ・prompt 文字の入力・promptFolder フォルダ選択）
アプリの機能の呼び出し（action）: zen.action("FileList.BatchRename") のように、キー割り当て画面に並ぶ約 100 個のアクションをそのまま呼べます。圧縮・解凍・Grep 検索・フォルダ比較・同期・一括リネーム・ハッシュ・お気に入りなど、マクロ専用の命令が用意されていない機能はこれで届きます。アクション名を打ち間違えると「近いもの」を添えたエラーになります。実行を開始するだけで終わるのは待たないため、続けて結果を触る場合は「⏱ 待機」を挟んでください
安全性: ファイル操作（作成・移動・リネーム・コピー・削除）は 現在表示しているフォルダ内に限定され、実行前に安全性が検証されます。..\ を使っても、フォルダの外を指す絶対パスを書いても、名前が似ているだけの隣のフォルダ（作業 を開いているときの 作業2 など）を指しても、実行前に止まります。ショートカット（シンボリックリンク・ジャンクション）を辿って外へ出る経路も同じく塞がれています。また 今開いているフォルダそのものを削除・移動・リネームの対象にはできません。あわせて、1 回のマクロで行える破壊的な操作は 500 件までに制限されています。
途中で止められます: 実行中はマクロスタジオのツールバーに 「⏹ 停止」 が出ます。押すとその場で中断し、そこまでに行った操作は 1 回の Ctrl+Z でまとめて戻せます。停止は、スタジオの ▶ から実行したものだけでなく、ナビペインの一覧・ステータスバー・ショートカット・コマンドパレットから実行したマクロにも効きます。マクロの実行中は次の実行を受け付けません（同じマクロが二重に走って同じファイルを取り合うのを防ぐためです）。
失敗した行が分かります: エラーは ❌ エラー: 3 行目: ... の形で、どこで落ちたかを添えて表示されます。書き間違い（構文エラー）も同じ形です。
まとめて取り消し: マクロで行った操作は、1 回の取り消し（Ctrl+Z）でマクロ全体をまとめて巻き戻せます。ただし削除（delete）は取り消しの対象外です — ゴミ箱へ送る操作はアプリの他の場所でも Ctrl+Z で戻せないためで、削除を含むマクロを実行すると、その旨が実行結果の末尾に表示されます（削除したものはゴミ箱から復元してください）。取り消しの途中で戻せないものがあった場合は、戻せなかった件数と対象が通知されます。

操作の記録¶

実際の操作をそのまま覚えさせて、マクロにできます。

ステータスバーの ⏺（記録開始）を押します。
いつもどおりに操作します。記録されるのは フォルダ移動・検索・アイテムの選択・コピー・移動・リネーム・ゴミ箱へ削除・フォルダ作成・タブの開閉 です。
記録を停止すると、操作内容が マクロスタジオのノード（部品）として自動的に開きます。そのまま部品を足したり、引数を書き換えたりできます。

そのまま実行したり、内容を編集したり、名前を付けて保存したりできます。

記録についての細かい点:

選択は「最後にどうなったか」だけが残ります。 選び直している途中の経過は記録しません。
現在フォルダの外へ出るコピー・移動は記録しません。 マクロのファイル操作は現在フォルダの中に限られるため、そのままでは再生できないからです（別のドライブへのドラッグなどが該当します）。
部品で表せない操作があった場合は、その部分だけ「🧩 スクリプト」部品として残ります（記録した内容が失われることはありません）。部品に戻せるものが 1 つも無かったときだけ、従来どおりコードタブで開きます。

AI 連携¶

zen.ai を使うと、AI に「ファイルの分類」や「整理アクションの提案」を依頼し、その結果に基づいて操作を実行できます（生成 AI の設定が必要です。設定方法は AI プロバイダー設定 を参照）。マクロスタジオの部品パレットから「🤖 AI整理」ブロックとして配置できます。

保存と再利用¶

マクロスタジオで名前を付けて保存できます（data フォルダ内の macros フォルダに保存されます）。既に保存済みのマクロを編集して保存すると上書き更新されます（新規マクロとして保存したいときは「複製」してから編集してください）。保存したマクロは次の場所から呼び出せます。

ナビペインの「マクロ」ビューの一覧（ダブルクリックまたは ▶ で実行）
ステータスバー右側の ⚡（保存マクロ）プルダウン（クリックで実行）

トリガー（自動実行）¶

保存した各マクロには、自動で実行する条件（トリガー）を設定できます。マクロスタジオのプロパティ列（保存済みマクロを編集対象にしているときのみ表示）から設定します。

🏁 起動時: アプリの起動時に自動実行します。
⏰ 毎日: 指定した時刻（HH:mm）に毎日自動実行します。
⌨ キー: 設定したショートカットキー（例: Ctrl+Shift+M）で実行します。
👁 監視（ホットフォルダ）: 指定したフォルダに変化があったとき自動実行します。

設定済みのトリガーは、ナビペインの一覧・マクロスタジオのライブラリ列にバッジとして表示されます。

安全に使うために¶

実行前の確認: zen.confirm による確認ダイアログや、実行前の検証（ドライラン）で、意図しないデータ損失を防ぎます。
未保存の変更の保護: マクロスタジオで編集中に、保存しないままライブラリの選択を切り替えたり、新規マクロを開始したり、ウィンドウを閉じようとすると、破棄してよいか確認するダイアログが表示されます。
無料版の上限: AI 機能やマクロの実行には、無料版では利用回数に上限があります（上限なくお使いいただくには Full 版が必要です）。

マクロスタジオ¶

ナビペインの「＋」、保存マクロの右クリック「スタジオで編集」、ステータスバーの「＋新規マクロ」などから、マクロスタジオが開きます。部品の名前・説明・入力例からプリセットまで、表示は 10 言語に対応しています（設定の表示言語に従います）。マクロの作成・編集を行う唯一の場所で、モードレス（別ウィンドウ）なので開いたまま裏でフォルダを閲覧・操作できます。3列構成です。

左: ライブラリ列 — 保存済みマクロの一覧です。選択すると編集対象が切り替わります（未保存の変更があれば確認）。右クリックで複製・書き出し・削除ができます。
受け渡し: 右クリックの「書き出す…」でマクロを 1 つの .json として保存でき、列の見出しにある「読み込む…」で取り込めます。取り込む前に、そのマクロが何をするか（ファイルを消す・移動する・AI に問い合わせる等）を一覧で確認してから決められます。 取り込んだマクロはその場では実行されず、中身を確かめられるようにスタジオで開きます。取り込み時に ID は振り直され、自動実行の設定（起動時・時刻・監視・ショートカット）は持ち込まれません（もらったマクロが取り込んだ瞬間に走らないようにするためです）。
中央: 編集面（ノード / コードタブ切替）
ノードタブ: 広い 2D キャンバス上で、部品（ブロック）をパズルのように組み合わせてマクロを作れます。
- AI に組ませる: キャンバス上部の入力欄にやりたいことを言葉で書いて「✨ AI生成」を押すと、マクロが組み上がった状態でキャンバスに並びます（例:「PDF を月別フォルダへ整理して通知」）。生成されたものは手で組んだマクロと同じもので、そのまま部品を足したり引数を変えたりできます。生成しただけでは実行しません — 中身を確認してから「▶ 実行」してください。イメージと違うときは、指示を書き直してもう一度押します。いま開いているフォルダの名前と中身（先頭 40 件）も一緒に渡すため、「選択中のファイルを」のような書き方が通じます（フォルダのフルパスは渡していません）。キャンバスに既にノードがあるときは、置き換えてよいか確認します。生成 AI の設定が必要です（AI プロバイダー設定）。生成中は「キャンセル」で打ち切れます。
- 並べ直す: キャンバス左上の「≡ 整列」を押すと、カードをつながりの順に並べ直します（直列は縦一列、条件分岐は「はい」を下・「いいえ」を右隣の列へ、くり返しは中身を右隣の列へ・そのあとを下へ）。AI 生成と同じ並べ方なので、手で組んだマクロも生成したマクロも同じ見た目になります。カードは作り直さないので、接続も入力した値もそのまま残り、位置だけが動きます。つながっていないカードは右端にまとめて置かれます。
- キャンバス操作: 空白部分を左ドラッグするとキャンバス全体をパン（視点移動）できます。Shift を押しながら左ドラッグすると矩形の範囲選択になり、複数カードをまとめて選択・移動できます。
- 部品を置く: 左の「部品」パレットからブロックをキャンバスへドラッグ&ドロップします（クリックでも追加できます）。各部品はマウスを乗せると用途の説明が出ます。カードを1つ選択すると、その出力につなぎやすい部品が部品パレット上に「★ おすすめ」表示され、次に置くブロックを迷わず選べます（実際によく使う組み合わせを覚えて精度が上がります）。
- つなぐ: ブロックの左右にある「穴」（コネクタ）どうしを線でつなぐと、上流→下流の実行順になります。連結線はカードの上に重ならないよう自動的に迂回して配置されます。
- 設定する（右ペインで・選ぶだけ）: カードをクリックすると、右ペインに「部品の設定」が開きます。カード自体は「何をする部品か」と「今の値」を読ませるだけで、値を変えるのはこの右ペインです（狭いカードの中で入力するより、はるかに扱いやすくなります）。入力欄は種類に応じて「📁 参照（フォルダ選択）」「現在フォルダの内容から選ぶ候補リスト」「{ } トークン（日付などの挿入）」「▾ プリセット（よく使う値）」を備え、なるべく手入力せずに設定できます。その部品が何をするものかの説明と、生成される JavaScript も同じ場所で確認できます。選択中のカードは枠がアクセント色になります。
- 条件分岐: 「🔀 条件分岐」ブロックは「はい / いいえ」の 2 つの出口を持ちます。条件（選択がある／アイテムがある／確認 OK／ファイルが存在／カスタム式）で処理を分けられ、実行時には if / else に変換されます。
- くり返し: 「🔁 くり返し」ブロックは「くり返す / そのあと」の 2 つの出口を持ちます。「くり返す」につないだ部品が中身、「そのあと」につないだ部品がループを抜けた後に動きます。回す対象は「フォルダの中身」か「選択中のアイテム」から選び、*.pdf のようなフィルタを添えられます（選択中のときフィルタは使いません）。くり返しの中では、いま取り出しているアイテムを {item}（名前）／{itemExt}（拡張子）／{itemPath}（フルパス）／{itemDate:yyyy-MM}（更新日時） のトークンで指せます（これらはくり返しの中でだけ意味を持ちます）。「PDF を全部月別フォルダへ移す」のような処理が、スクリプトを書かずに組めます。
- 実行時に値を尋ねる: 引数欄に {prompt:接頭辞を入力} と書くと、実行時に入力欄が出て、入れた文字がそこへ入ります。{promptFolder} ならフォルダ選択のダイアログが出ます。1 つのマクロを値だけ変えて使い回せます。入力をキャンセルするとマクロはその場で止まります。
- スクリプト部品: 「🧩 スクリプト」ブロックは、右ペインの「部品の設定」で JavaScript を直接書ける部品です。「拡張子ごとに仕分ける」「一定サイズを超えるものだけ移す」のように、一覧を回して条件で分ける処理など、ほかの部品では表せないことに使います。書いた内容はそのままマクロの一部として動きます（使える命令は 実行の仕組み（zen.* API） の zen.* API）。
- 使える部品の例: 移動・フォルダ作成・リネーム・整理移動・コピー・ゴミ箱へ削除（復元可能）・検索・選択・通知・ログ・新規タブ・タブを閉じる・親フォルダへ・ホームへ・一覧更新・待機・AI 整理・連番リネーム・条件分岐・くり返し・スクリプト。
- カード幅の調整: 各ノードカードは右端のグリップを左右にドラッグして幅を変えられます。拡大したり、カード自体をドラッグ移動したりして重なる位置にきた後続カードは、自動的に位置をずらして避けます。
コードタブ: 生成された JavaScript を確認できます。手書き・記録直後のマクロ（ノードを持たない）はここで直接編集できます。ノードグラフ由来のマクロは、手編集との食い違いによる上書き事故を防ぐため読み取り専用になります（編集はノードタブで行ってください）。行番号が表示され、予約語・文字列・数値・コメントが色分けされます（色はテーマから引くので、どのテーマでも読めます）。「🧩 スクリプト」部品の入力欄も同じ見た目です。
右: プロパティ列 — 上段は選択中カードの「部品の設定」（カードをクリックすると開きます）。その下でマクロの名前・説明を編集し、保存済みマクロならトリガー設定（起動時・毎日・キー・監視）を行えます。直近の実行結果は常に最下部に表示されます。
実行履歴: 実行結果の下の「実行履歴」を開くと、直近 30 件が実行時刻・マクロ名・成否・所要時間とともに新しい順に並びます。行の頭の印は実行元で、▶ 手動 / ⏻ 起動時 / ⏰ 時刻指定 / 👁 フォルダ監視です。マウスを載せると結果の要約（失敗ならその理由）が出ます。自動実行したマクロが動いたかどうかは、ここで確かめます。 200 件を超えると古いものから消え、「履歴を消す」で空にできます。
ツールバー: 「＋新規」で新規マクロ状態にリセット、「▶ 実行」で実行、「⏺ 記録開始／⏹ 記録停止」で操作記録、「💾 保存」で保存（既存マクロを開いている場合は上書き更新）します。