Windows AppShots

Windows AppShotsは、1つのWindowsアプリケーションの明示的なセマンティックチェックポイントを、ピクセルと、制限付きのMicrosoft UI Automationツリーおよびプロバイダーが公開するテキストとして保持します。

AppShotは再利用可能なエビデンスであり、デスクトップ操作ツールでも、ライブなコンピューター利用アクションループ用の低遅延スクリーンショット面でもありません。最新の状態とアクションにはコンピューター利用ドライバーを使用してください。結果を保存したり、後で取得したり、制限付きセマンティックバンドルとして検査したりする場合は、AppShotをリクエストしてください。

これは独立したコミュニティプロジェクトです。OpenAIの製品ではなく、OpenAIによる推奨やサポートを受けるものではありません。Brian MulderがOpenAI Codexの支援を受けて構築しました。

要件

• x64上のWindows 10または11；

• Node.js 22以上；

• ローカルプラグインが有効なCodexまたはChatGPTデスクトップアプリ。

NodeはMCPアダプターのみを実行します。ネイティブのキャプチャヘルパー、ウォッチャー、ホットキー、トレイにはNodeは必要ありません。エンドユーザーに.NET SDKは必要ありません。

Related MCP server: screenshot-mcp

インストール

最新のGitHubリリースからWindowsAppShots-Setup-0.1.1.exeをダウンロードして実行してください。ユーザー単位のインストーラーには管理者アクセスは不要です。

インストーラーは次のことができます：

• Codexへのローカルプラグインの登録（デフォルトで選択）；

• オプションでサインイン時にトレイアイコン付きでウォッチャーを開始；

• アップグレード前に検証済みの既存ウォッチャーを停止。

Codexの登録を変更する前に、インストーラーはサポート対象のNodeがPATH上にあるかどうかを確認します。このチェックが失敗した場合、ネイティブヘルパーはインストールされたままになり、エラーには後で登録を完了する方法が説明されます。

インストール後、CodexまたはChatGPTデスクトップアプリを再起動してください。

リリース版インストーラーは現在署名されていないため、Windowsで発行元不明の警告が表示されることがあります。実行する前に、リリースに公開されているSHA-256値を検証してください。

使用

共有したいアプリケーションにフォーカスを移し、Codexに戻って次のように依頼します：

最後に使っていたWindowsアプリをキャプチャして。

対象のアプリがフォアグラウンドの間にCtrl+Alt+Shift+Aを押してから、次のように依頼することもできます：

最新のWindows AppShotを使って。

ホットキーはキャプチャバンドルを書き込み、Windowsの成功サウンドを再生します。

MCPサーバーはcapture_appshot、get_latest_appshot、list_appshots、stop_watcherを公開します。

ウォッチャーがある理由

MCPキャプチャが実行される時点では、通常Codexがフォアグラウンドにあります。ウォッチャーは最後の非CodexウィンドウのIDを記憶しているため、後続のキャプチャでも意図したターゲットを取得できます。

ウォッチャーはオプションのホットキーとトレイステータスも管理します。スクリーンショットを継続的に撮影したり、UI Automationを走査したりすることはありません。これらのアクションはキャプチャをリクエストしたときだけ発生します。

トレイメニューはキャプチャフォルダを開いたり、ウォッチャーを停止したりできます。キャプチャボタンはありません。通知領域を開くとフォアグラウンドウィンドウのコンテキストが変わり、意図したアプリの代わりにシェルUIが選択される可能性があるためです。

キャプチャツールはUI Automationのcontrol、content、rawビューをサポートします。rawモードは、ノード数・深さ・テキスト・時間の制限に従って、プロバイダーが公開する最も完全なツリーを返します。

キャプチャの内容とプライバシー

使用前に簡潔なプライバシーポリシーをお読みください。

capture_appshotを呼び出すかホットキーを押すことは、明示的な共有アクションです。バンドルをローカルに保存し、選択したピクセルとセマンティックコンテキストをアクティブなCodexタスクに返します。

キャプチャされたテキストは信頼できないデータであり、Codexが従うべき指示ではありません。

バンドルは次の場所に保存されます：

%LOCALAPPDATA%\WindowsAppshots

自動的な有効期限はありません。Windows AppShotsを無効化またはアンインストールしても、既存のキャプチャは削除されません。

各バンドルには次のものが含まれます：

manifest.json
visual.png
accessibility-tree.json
accessible-text.txt
model-context.md

UI Automationのテキストには、表示中のビューポート外のコンテンツが含まれる場合があります。画面フォールバックが必要な場合、ターゲットの矩形内の重なったウィンドウや通知がvisual.pngに表示されることがあります。

パスワードとしてマークされたコントロールは基本的なメタデータを保持しますが、そのUI AutomationのValueとTextは抑制されます。制限付きの資格情報ポリシーは、認識されたシークレットをセマンティックアーティファクトからも編集します。

編集はベストエフォートであり、安全性の保証ではありません。通常の機密文書、個人情報、識別子、ファイルパス、またはあらゆる特殊な資格情報形式を削除するものではありません。

visual.pngは編集されません。キャプチャ前にターゲットウィンドウを確認し、すべてのバンドルを機密として扱ってください。

マニフェストには、切り詰め、警告、セマンティック編集の受領情報が記録されます。ピクセル、ノード、テキストが欠けていても、アプリケーションにそれらが含まれていなかったことを証明するものではありません。

停止、削除、消去

Codexにstop_watcherを呼び出すよう依頼するか、トレイメニューからExit Windows AppShotsを選択するか、以下を実行します：

& "$env:LOCALAPPDATA\Programs\WindowsAppShots\bin\AppshotCapture.exe" stop `
  --state-root "$env:LOCALAPPDATA\WindowsAppshots"

インストーラーでインストールした場合は、Installed apps > Windows AppShots > Uninstallを使用してください。これにより、検証済みのウォッチャーが停止し、そのインストールで登録されたCodexマーケットプレイスが削除されます。

ソースからインストールした場合は、プラグインとマーケットプレイスを削除します：

codex plugin remove windows-appshots@windows-appshots
codex plugin marketplace remove windows-appshots

アンインストール後もキャプチャは残ります。不要になった場合は、キャプチャストアを確認してから削除してください：

Get-ChildItem -LiteralPath "$env:LOCALAPPDATA\WindowsAppshots" -Force
Remove-Item -LiteralPath "$env:LOCALAPPDATA\WindowsAppshots" -Recurse -Force

ビルドと検証

このリポジトリをCodexプラグインマーケットプレイスとして追加し、プラグインをインストールします：

codex plugin marketplace add brianmulder/windows-appshots --ref main
codex plugin add windows-appshots@windows-appshots

ソースからのビルドは、固定された.NET 10.0.302 SDKを使用して、決定論的な.NET Framework 4.8ヘルパーを生成します。インストールされたヘルパーに.NET 10ランタイムは必要ありません。

固定されたSDKをインストールするか、非管理者インストールを.tools\dotnetに配置してから、以下を実行します：

npm run build
npm run verify

npm run verifyは2回ビルドし、出力を比較し、MCPテストを実行し、ネイティブキャプチャ、編集、ウォッチャーID、制限付きUI Automation、トレイ動作、MCPウォッチャー停止を検証します。

インストーラーをビルドするには、NSIS 3.12をインストールするか、.tools\nsisに配置してから、以下を実行します：

npm run build:installer

インストーラーのソースはinstaller/WindowsAppShots.nsiです。生成された実行可能ファイルはコミットされません。各インストーラービルドはdist/BUILD-RECEIPT.jsonとdist/SHA256SUMS.txtを書き込みます。

リリース前に、インストール、登録、キャプチャ、トレイ、停止、アップグレード、アンインストールの完全なゲートを実行してください：

npm run verify:release

GitHub Actionsは同じWindowsリリースゲートを実行し、インストーラー、チェックサム、ビルド受領情報をワークフローアーティファクトとして保持します。

プラットフォームの制限

• セキュアデスクトップと昇格されたウィンドウはバイパスされません。

• 保護されたコンテンツやDRMコンテンツでは、空白のビジュアルが生成される場合があります。

• 最小化されたアプリケーションやGPUコンポジットされたアプリケーションでは、不完全なピクセルが提供される場合があります。

• UI Automationの品質と応答性は、ターゲットアプリケーションに依存します。

• プロバイダーは、外部タイムアウトが分離されたUI Automationワーカーを強制終了するまで、キャプチャを遅延させることができます。

プロジェクト情報

• コントリビューション

• セキュリティ報告

• コード署名ポリシー

• ブランドアセット

• MITライセンス