notis-desktop-use

Notis デスクトップ操作スキル

ユーザーの実際の Macを操作する必要があるタスク（画面のキャプチャ、ネイティブアプリの UI の確認、ボタンのクリック、文字の入力、メニューの操作、ウィンドウの移動など）では、このスキルを使用します。エンジンは Peekaboo です。Swift コアを基盤とする、署名・公証済みの macOS 自動化 CLI です。

これはユーザー自身のコンピューターの GUI 操作です。ブラウザーの自動操作でも、サンドボックスでもありません。Web ページには notis-browser-control を使用してください。隔離された再現可能な環境には Cloud Computer を使用してください。Peekaboo は稼働中の macOS Aqua セッション、画面、TCC 権限を必要とするため、ユーザーの local_shell でのみ実行できます。

手順 0：最初にローカルシェルに切り替える（必須。Cloud エージェントは下記を参照）

Peekaboo はユーザーの実機の Mac を操作するため、すべてのコマンドをローカルシェル（Notis デスクトップブリッジ）で実行する必要があります。Cloud Computer では実行しないでください。シェル呼び出しのデフォルトは sandbox_shell です。この手順を省略すると、peekaboo コマンドは /vercel/sandbox で実行されます。そこには Peekaboo がなく、Mac を操作できません。

peekaboo コマンドを実行する前に、mode: "local_shell" を指定して set_shell_mode を呼び出してください。

• 成功した場合、以降のシェル呼び出しはすべてユーザーの Mac で実行されます。そのまま続行してください。
• ユーザーが複数のコンピューターを所有している場合、結果の computers に一覧が表示されます。画面操作にはユーザーが直接見ている必要があるため、ユーザーが現在その場にいる Mac（user_is_at_it_now）を選び、computer としてその名前を渡してください（set_shell_mode または LOCAL_NOTIS_RUN_DESKTOP_SHELL に指定します）。別のコンピューターを指定するまでは、この会話で最後に使用したコンピューター上でコマンドが実行されます。
• Your Computer は Free を含むすべてのプランで利用できます。この呼び出しが予期せず entitlement_upgrade_required を返した場合は、アクセス権ポリシーの不一致を報告して停止してください。Ultra へのアップグレード案内に置き換えてはいけません。entitlement_check_unavailable が返された場合は、再試行するようユーザーに依頼してください。
• Notis デスクトップアプリが接続されていないというエラーが返された場合は、Notis デスクトップアプリを開き、設定で Your Computer（コンピューターの使用）をオンにするようユーザーに伝えてから停止してください。サンドボックスで peekaboo を実行してはいけません。また、デスクトップ操作を偽装するためにブラウザーツールに切り替えてはいけません。

cd /vercel/sandbox を実行したり、サンドボックスの作業ディレクトリを想定したりしてはいけません。ローカルシェルで peekaboo を直接実行してください。

Cloud Computer 上の Codex エージェントと Claude エージェントには set_shell_mode がありません。この手順は省略し、このスキルの各コマンドを Mac 上で次のように実行してください。エラーの意味は上記と同じです。

notis tools exec LOCAL_NOTIS_RUN_DESKTOP_SHELL --arguments '{"command": "...", "timeout_ms": 60000}' --timeout-ms 90000

読み取り専用のステータス確認 — 最短の検証済みループ

名前を指定したネイティブアプリの場合、シェルモードを切り替えた後に次の手順を実行します。

1. このセッションでは peekaboo permissions status --json を一度だけ実行します。 名前を指定したアプリを調査する場合、すでに前面に表示されている場合を除き、 キャプチャの前に peekaboo app focus "APP NAME" --foreground --json を実行して 表示します。これは調査中のナビゲーションであり、データの編集を許可するものでは ありません。利用できないウィンドウや非表示のウィンドウを繰り返しキャプチャしたり、 そのアプリの内容の代わりにメニューバーをキャプチャしたりしないでください。
2. 名前を指定したアプリを直接キャプチャします：peekaboo see --app "APP NAME" --json。 このシェル呼び出しでは max_output_length: 200000 を指定します。role: "other" の 静的ラベルも含めて data.ui_elements とその境界を確認します。ステータスの見出しは メニューやコントロールより後の配列の末尾近くに表示されることがあります。 stdout を 30000～50000 文字に切り詰めると、必要なステータステキストが 気付かないうちに隠れてしまうことがあります。対象がわかっている場合は、実行中の アプリをすべて列挙しないでください。
3. これらのラベルから要求された事実を確認できたら、すぐに報告します。表示されている ステータスグループと、実際に実行中のエージェントの違いを保ってください。 折りたたまれている項目、画面外の項目、未確認の項目は、明示的にそのように伝えます。 ステータスを推測しないでください。不足している具体的な事実を確認する場合に限り、 さらに調査してください。

ここにあるコマンド例をまず使用してください。インストール済みのバージョンでフラグが 拒否された場合や、記載されていないオプションが必要な場合は、そのコマンドの --help を確認してください。単純なステータス確認のためにツールカタログ全体を 読み込まないでください。同じ変更のない UI を重複してキャプチャしたり、フィルター なしの巨大な JSON ダンプを取得したりしないでください。

テキストだけの小規模な調査には、peekaboo see --tree --no-screenshot --app "APP NAME" --max-elements 300 --depth 20 --json を使用してください。 data.ui_elements と、切り詰めに関する警告を確認します。部分的なツリーは、項目が 存在しないことの証明にはなりません。どちらのキャプチャ形式でも --app を使用します。 semantic_scope が application_partial の場合、ラベルはアプリレベルのコンテキストで あり、要求されたウィンドウの証明ではありません。また、再利用可能なスナップショットも 変更を実行する権限もありません。

アクセシビリティテキストだけでは不十分な場合は、コマンドとキャプチャのガイドを 使用してください。スクリーンショットコマンドの成功で証明できるのは、ファイルが キャプチャされたことだけです。シェル stdout にパスが表示されても、その画像を見た ことにはなりません。画像を読み取るツールが利用できない場合は、視覚的に確認したと 主張しないでください。Peekaboo の AI 機能（--analyze、see の分析機能、 peekaboo agent）は絶対に使用しないでください。これらは、独自の API キーを持つ 別途設定されたモデルプロバイダーにキャプチャを送信します。視覚的な推論は現在の ハーネスで行ってください。視覚的に確認できない点が残る場合は報告してください。

Peekaboo はすでにインストール済みです — インストールしないでください

Notis デスクトップアプリは、ユーザーがコンピューター操作を有効にすると、ピン留め された Peekaboo をインストールして管理します（PATH 上にあります）。そのため：

• brew install の実行、リリースのダウンロード、~/bin/peekaboo の確認は しないでください。
• ローカルシェルに切り替えたら、peekaboo … をそのまま実行してください。

ローカルシェルで peekaboo --version が失敗する場合、Peekaboo のインストールが 完了していません。Notis デスクトップの設定で Your Computer を一度オフにしてから 再度オンにするようユーザーに伝えてください（これによってインストールが開始されます）。 その後、もう一度試してください。自分でインストールしようとしないでください。

呼び出しごとに単独のコマンドを1つだけ実行 — コマンドを連結しない

シェル呼び出しごとに、peekaboo の呼び出しは1つだけ実行してください。&&、 ||、;、パイプ（|）、リダイレクト、cd と組み合わせないでください。単独の peekaboo コマンドは、承認を求めずにローカルシェルで自動実行されます。コマンドを 連結したりパイプでつないだりすると、この動作が無効になり、ブロックされたりユーザーに 確認を求めたりします。インラインでパイプを使わず、後の手順で --json を使って出力を 解析してください。

# Good — runs immediately:
peekaboo --version
peekaboo see --json

# Bad — chained/piped, will be blocked or prompt:
~/bin/peekaboo --version || peekaboo --version
peekaboo app list --json | python3 -c '...'

権限は必須です — 操作前に確認してください

Peekaboo は、macOS の TCC 権限が付与されていないと、キャプチャや自動操作を実行できません。必ず最初に権限を確認し、不足している権限をユーザーに伝えてください。権限をプログラムから付与することはできません。

peekaboo permissions status --json
peekaboo permissions status --all-sources   # compare Bridge host vs local CLI

各機能に必要な権限（システム設定 → プライバシーとセキュリティ）：

• 画面収録 → スクリーンショットとピクセルのキャプチャに必要です。権限の確認結果に表示される実行ホストを有効にしてください。管理対象のデスクトップをアップグレードした後は、有効な項目が現在のホストを指しているか、再確認してください。
• アクセシビリティ → クリック、文字入力、キー入力、ウィンドウ操作、AX の検査に必要です。確認結果に表示される実行ホストを有効にしてください。
• イベント合成 → peekaboo permissions request event-synthesizing（ローカルの CLI プロセスに対して要求するには --no-remote を追加します）。フォーカスを奪わずに、受信側を指定した文字入力、キーの組み合わせ、貼り付けを可能にします。権限の設定が許可されている場合にのみ要求してください。通常の読み取り専用の検査中に権限を変更しないでください。

必要な権限が不足している場合は、切り替えるトグルをユーザーに正確に伝え、続行する前に peekaboo permissions status --json を再実行してください。キャプチャに失敗しても、繰り返し試行しないでください。

リモート／バックグラウンドセッション

SSH、LaunchAgent、cron、その他のバックグラウンドの launchd セッションでは、TCC 権限が付与されているように見える場合でも、Peekaboo の Bridge 経由で操作してください。CoreGraphics は成功を報告していても、デスクトップの壁紙だけを返したり、画像をマスキングしたりすることがあります。リモートの Mac では、アクセシビリティ経由のクリックや文字入力は機能していても、画面収録がブロックされることがあります。対象の UI をそれ以外の方法で把握できる場合は、諦めずに、許可されたクリックや see --tree --no-screenshot を続けてください。

座標クリック：正確なスナップショットまたは明示的なフォアグラウンド操作

最新かつ正確なウィンドウのスナップショットがない場合、座標クリックには明示的なフォアグラウンドへの入力が必要です。そのアプリにフォーカスして操作することがユーザーのタスクの範囲内である場合にのみ使用してください。対象のウィンドウにフォーカスしてから、グローバル画面座標を --foreground とともに使用します。

peekaboo window focus --app "Dia" --window-id 118166 --foreground --json
peekaboo click --at 672,607 --global --app "Dia" --window-id 118166 --foreground --json

see／see --tree で要素 ID やクエリが得られる場合は、それを使ってクリックしてください。座標はそれらが使えない場合にのみ使用してください（次のセクションを参照）。

ブラウザー／Web アプリ：アクセシビリティで情報が不十分な場合はスクリーンショットを使用

ページが表示されていても、一部のブラウザーや Web アプリの画面では、役立つアクセシビリティテキストが公開されていません。対象を絞った検査を一度行っても結果が空または不完全な場合は、see／see --tree を繰り返さず、利用可能なビジョン経由の方法に切り替えてください。

1. ウィンドウをキャプチャします：peekaboo see --no-elements --app "Dia" --window-id <id> --mode window --path /tmp/shot.png --json （<id> は peekaboo window list --app "Dia" --json から取得します）。
2. そのスクリーンショットで、操作対象を目視で確認します。
3. 返された coordinate_context（画像のスケールとビューポートの原点を含む）を使って、スクリーンショット上のピクセル座標をグローバルな論理画面座標に変換します。Retina のピクセルが画面座標と同じだと決めつけたり、古いウィンドウ境界を使ったりしないでください。対応関係が得られない、または不確かな場合は、推測せずに再キャプチャしてください。
4. 対象のウィンドウにフォーカスしてから、click --at X,Y --global --app "Dia" --window-id <id> --foreground --json（上記参照）を実行し、続けて see を再実行して、要求された結果を確認します。バックグラウンドで座標を使うには、最新かつ正確なウィンドウのスナップショットが明示的に必要です。拒否された場合に、気付かれないままフォアグラウンド操作へ切り替えてはいけません。

space などのキーボードショートカットは Web プレーヤーを確実に操作できるとは限りません（ブラウザーでは、スペースキーでページがスクロールします）。代わりに、画面上の実際の再生／一時停止コントロールをクリックしてください。

安全ルール

• UI 操作は、ユーザーが依頼したタスクの範囲内でのみ行ってください。読み取り専用の調査では、ユーザーが画面遷移を禁止していない限り、指定されたアプリにフォーカスしたり、読み取り専用のステータスグループを展開したりできます。ただし、編集、送信、エージェントの停止、設定の変更は許可されません。破壊的な操作には明示的な許可が必要です。
• 画面はプライベートなものとして扱ってください。タスクに必要な範囲を超えてスクリーンショットや画面上のコンテンツを外部に持ち出さないでください。また、無関係なウィンドウをキャプチャして転送しないでください。
• 明示的なユーザー確認なしに、取り消せないシステムダイアログ（削除の確認、購入、送信など）を表示する操作は避けてください。判断に迷う場合は、peekaboo dialog list でダイアログをキャプチャし、クリックする前に確認を求めてください。
• ローカルの TCC の動作をテストする場合は --no-remote を優先し、バックグラウンドまたはリモートでキャプチャする場合は Bridge パスを使用してください。

アンチパターン

• local_shell を指定して set_shell_mode を呼び出す前に peekaboo を実行しないでください（Cloud Computer の Codex および Claude エージェントでは、代わりに LOCAL_NOTIS_RUN_DESKTOP_SHELL 経由で実行してください）。デフォルトの sandbox_shell では /vercel/sandbox 内で実行されるため、Peekaboo は存在しません。その場合、コマンドは「失敗」し、実際には権限の問題ではないにもかかわらず、権限の問題のように見えます。
• cd /vercel/sandbox（または任意の sandbox パス）を実行したり、sandbox の作業ディレクトリを前提にしたりしないでください。ローカルシェルで peekaboo を直接実行してください。
• Peekaboo をインストールしないでください（brew install、ダウンロード、~/bin の確認は禁止です）。Notis デスクトップアプリはすでにインストール済みで、PATH 上で管理されています。
• peekaboo を &&、||、;、パイプ、リダイレクト、cd と連結しないでください。プロンプトなしで自動実行されるよう、1 回の呼び出しにつき通常のコマンドを 1 つだけ実行してください。
• 座標だけを指定してクリックしないでください（peekaboo click X,Y）。最新の正確なウィンドウスナップショットを使って --at を指定するか、明示的に許可された --foreground ターゲティングを使用してください。
• 有用なアクセシビリティテキストが得られないブラウザページを、繰り返し調査しないでください。利用可能な画像読み取り手段を使うか、その制約を報告してください。
• Web 動画の再生に space／キーボードを使わないでください。画面上の再生コントロールをクリックしてください。
• 権限の確認を省略しないでください。許可がない場合、明確なエラーではなく、壁紙のみ、または空のキャプチャが返されます。
• スナップショット間で要素 ID を使い回したり、最新の see を取得せずに操作したりしないでください。スナップショットを対象とする操作では、返された data.snapshot_id を --snapshot にコピーしてください。その操作の後、次の操作を行う前に再度キャプチャしてください。
• 終了コード 0 や success: true を、依頼された UI 変更が実現した証拠と解釈しないでください。操作の effect、retry_safe、requires_fresh_observation、および error.hint を確認してください。partial、unverifiable、suspected_noop、または不確かな失敗の場合は、再試行の前に状態を確認してください。refused は、ターゲット範囲を広げたり、フォアグラウンド入力を有効にしたりする許可ではありません。読み取り専用の結果では effect が省略されることがあります。confirmed の後も、特に入力、キー操作、送信については、ユーザーが意図した結果を確認してください。
• このスキルに記載されたコマンド例を使用してください。例が拒否された場合や追加のフラグが必要な場合は、該当するコマンドの --help を参照してください。
• ユーザーのマシンに無関係な入力を送らないでください。画面遷移は依頼された調査の範囲内にとどめ、データの変更には別途許可が必要です。

コマンドの確認方法とスクリーンショット／操作のループについては、command-and-capture を読んでください。必要なコマンドがどれであっても、ローカルシェル、権限、最新のスクリーンショット／要素 ID、フォアグラウンドのターゲティング、およびユーザーが許可した入力は必須です。

タスクガイド

このタスクに必要なガイドのみを、このスキルバンドルから読んでください。

• コマンドとキャプチャのガイド