hadimoti/joy-media-windows-mcp

Windows-MCP で JOY Media を操作する

このスキルは、JOY Media 1.1.0 ビルド（Electron 44.3.0、Windows 11）で学習された手法です。エージェントに対して、ユーザーの実際のインストールやデータに触れることなくデスクトップアプリを実行し、Windows-MCP ツールでエディタをクリック操作し、外見ではなく事実に基づいてエクスポートを評価する方法を指示します。

使用ツール: Snapshot、Screenshot、Click、Type、App、Wait（Windows-MCP）、および PowerShell（起動、ファイル確認、ffmpeg/ffprobe 用）。

0. 基本ルール（必ず守る）

• 毎回の実行前にオーナーに確認すること。 アプリの起動、インポート、エクスポートには、オーナーが PC の前にいて、その実行に対する明確な「GO」が必要です。一度に一つの実行のみ。決してユーザーの実際のプロファイルに対して起動しないでください。
• インストール済みアプリには絶対に触れない（そのフォルダ、インストーラースクリプト、アンインストーラー）。代わりに、別の展開済みコピーを実行してください（セクション 1）。
• データを隔離する: 常に新しい --user-data-dir を渡すこと。既存のプロジェクトを再利用するには、アプリを閉じてから robocopy /E で古いプロファイルを新しいフォルダにコピーし（/MIR なし、消去なし）、コピー上で起動します。
• joy:// の登録キー（HKCU\Software\Classes\joy）は変更してはなりません。起動前、起動後、終了後にそれぞれ reg export で新しいファイルにエクスポートし、SHA-256 を比較してください。異なる場合は停止してオーナーに伝え、オーナーの指示があった場合のみ復元します。
• テスト中は何も削除しない（コピー、プロファイル、エクスポートは証拠です）。Chromium が新しいテストプロファイル内で自身の一時ファイルをクリーンアップすることは問題ありません。
• クラッシュの兆候で停止する（GPU プロセスの終了、Application Error イベント、ドライバーのリセット）：すべてを保持し、その上で再実行せず、オーナーに伝えてください。
• アプリ内にシークレットを入力したり、メモにトークンを記入したりしないでください。

1. 実行しても安全なアプリコピーを入手する

目的のコミットをビルドまたは展開し、短いパス（260 文字未満、例 C:\jg\app-<sha>）に配置します。

1. git archive <sha> で tar を作成し、C:\jg\<name> に展開します。
2. pnpm install --offline --frozen-lockfile（pnpm ストアがウォームされている必要があります）。
3. 既存のコピーの node_modules\.pnpm\electron@<ver>\node_modules\electron から Electron の dist フォルダと path.txt をコピーします（オフラインインストールでは Electron をダウンロードしません）。electron.exe の SHA-256 を確認します。
4. pnpm build を実行し、次に pnpm --filter @joy-media/desktop package:unpacked を実行します。
5. robocopy apps\desktop\dist\joy-media-unpacked C:\jg\app-<sha> /E を実行します。

展開済みコピーは isPackaged = false で実行されるため、joy:// プロトコルを登録しません。念のためキーを確認してください。

2. 起動する（PowerShell）

$env:NODE_ENV = 'production'
$app = 'C:\jg\app-<sha>'
Start-Process -FilePath '<path to>\electron.exe' `
  -ArgumentList @($app, '--user-data-dir=C:\jgp\<new-profile>', '--enable-logging=stderr') `
  -WorkingDirectory $app `
  -RedirectStandardOutput 'C:\jgp\run\stdout.log' -RedirectStandardError 'C:\jgp\run\stderr.log' -PassThru

--enable-logging=stderr はレンダラーの console.* 行を stderr ファイルに出力します（一時的な診断に便利）。プロセスコマンドラインに --joy-media-gpu-encode-fallback が含まれていないことを確認してください（それはフォールバックの再起動であり、デフォルトの起動ではありません）。ウィンドウタイトルは JOY Studio です。新しいプロファイルではアプリはプロジェクトページを開き、コピーしたプロファイルでは最後のプロジェクトを復元します。

3. Windows-MCP でウィンドウを操作する

スケール: スクリーンショットは実際の画面より約 2.56 倍小さくなります。常に Snapshot からの実際の座標をクリックし、スクリーンショットのピクセルは使用しないでください。各ページ変更後は小さな Screenshot（scale 0.4）を撮影してください。

順序: ウィンドウアクションは一度に一つ発行してください。一度、エクスポート直後にバッチを送信したところ、クリックとタイピングが間違ったプロジェクトに着地しました。App switch "JOY Studio" は時々「無効なウィンドウハンドル」で失敗します。ウィンドウが既に前面にある場合は続行してください。

以下の座標は、4920x2160 の画面で JOY ウィンドウがデフォルトのサイズと位置にある場合のものです。これらは開始時のマップであり、約束ではありません。何かが異なって見える場合は Snapshot を撮り、要素リストを使用してください。

アクション	場所（実際の座標）
ファイルメニュー	(910, 288)
ファイル > プロジェクトライブラリ	(1077, 358)
新規プロジェクトボタン	(3023, 311)、次に名前フィールドをクリック (1165, 727)、名前を Type し press_enter
最初のプロジェクトカード	(1680, 873)
タイムライン「メディアをインポート」（空のタイムライン）	(2199, 1312)
ファイルを開くダイアログ：名前ボックス / 開く	(1587, 1208) / (2268, 1264)
MP4 書き出し	(2672, 288)
クリップを選択、スケールを確認	クリップバーをクリック (1762, 1349)；インスペクターにスケール X/Y が表示されます
アプリウィンドウを閉じる	(3143, 288)
保存ダイアログ：名前ボックス / 保存	約 (1717, 1058) / (2283, 1266)

1つのケースのレシピ：プロジェクトライブラリ > 新規プロジェクト > 名前 > メディアをインポート > 完全なファイルパスを入力 > 開く（クリップがタイムラインに配置されます） > プレビューを確認 > MP4 書き出し > 待機 > ダイアログを保存 > 検証。

保存ダイアログについて。 書き出しは通常の Windows 保存ダイアログで終了します（デフォルトのフォルダはダウンロード、提案される名前には拡張子なし）。ファイルがデスクトップに到達するのは誰かが保存した後でのみであるため、「ワーカー終了」と「ファイルがデスクトップ上にある」の間の遅延は、単にそのダイアログが待機しているためです。ワーカーが完了すべきタイミングでスクリーンショットを撮影します。オーナーが保存するか、（オーナーの OK を得て）完全なターゲットパス ...\Desktop\<提案された名前>.mp4 を名前ボックスに入力し、「保存」をクリックします。アプリデータベース内のジョブタイミングは、この待機時間の影響を受けません。

4. 実行前、実行中、実行後

実行前：reg export で joy:// キーをエクスポートしハッシュ化します。ユーザーの実際のプロファイルフォルダと証拠フォルダをリストします（scripts/list-tree.ps1）。何も変更されていないことを証明できるようにするためです。

実行中（長時間のエクスポート）：バックグラウンドで scripts/sampler.ps1 -Pattern '*<profile>*' -Out <csv> -Stop <stopfile> を開始します。これは、Electron プロセスごとに、ワーキングセット、プライベートバイト、CPU 秒、NVENC セッション、GPU 使用率を毎秒記録します。停止ファイルを作成して終了します。

実行後：アプリを閉じ（閉じるウィンドウボタン）、electron プロセスが残っていないことを確認し、再度キーをエクスポートし、フォルダを再度リストして差分を確認し、プロファイル内に *.upload の残骸がないか確認し、Application Error/WER および Display/nvlddmkm イベントを確認します（Docker などの無関係なノイズは無視します）。

5. エクスポートを事実に基づいて評価する

• ffprobe -show_streams：コーデック、サイズ、フレーム数、 duration、カラータグ（color_space、color_primaries、color_transfer、color_range）。
• フルデコードはクリーンである必要があります：ffmpeg -v error -i out.mp4 -f null - で終了コード 0。
• ファイルをハッシュ化します（Get-FileHash）。同じコードパスであれば、同一のレイアウトから異なるビルドで同一のハッシュが得られるはずです。
• アプリ独自のデータベースからのフェーズタイム（joy-media.sqlite3 のコピーとその -wal/-shm を読み取り専用で開く）：scripts/export-times.py <copy> は、エクスポートごとに、ブラウザフェーズ（クリックタイムスタンプからステージングオリジナルまで）、ステージングバイト数、ワーカー時間を出力します。クリックタイムスタンプはファイル名の 13 桁の数字です。
• 色精度：scripts/fxgen.py <folder> でフィクスチャをビルドします（既知の sRGB 値を持つフラットカラーパッチとバイナリフレームカウンター、BT.709、BT.601、タグなし SD、フルレンジ、回転、VFR、10 ビット、HEVC、VP9、AV1、インターレース、トランジションペア、オーディオレートペア）。scripts/fxcheck.py <folder> で確認し、JOY_FX_DIR=<folder> python -I scripts/fxplace.py <export.mp4> <fixture-file-name> [frame] でエクスポートをスコアリングします。クリップがどこに着地したか（キャンバスより小さいクリップは 1:1 で左上に配置され、スケーリングされません）を特定し、4 つのマトリクス/レンジ読み取り値の下で最悪/平均偏差を出力します。正しい読み取り値は約 3 レベル以内である必要があります。
• オーディオ：astats のゼロクロスレートによるピッチ、RMS によるレベル。モノラルソースはステレオになります（チャンネルあたり約 3 dB 低くなります）。

6. 覚えておく価値のある既知の動作（JOY Media 1.1.0 ビルド）

• すべての色テストは新しいアプリセッションで実行すること。 テスト済みマシン（RTX 5070 Ti、Electron 44.3.0）では、起動後の最初のエクスポートは BT.709（タグ bt709）でエンコードされ、同じセッション内の以降のエクスポートは BT.601（タグ smpte170m）でエンコードされ、サイズが大きく、長いレイアウトでは遅くなり、バイト数も異なります。診断ビルドでは、キャプチャキャンバスフレームが最初は RGBA（GPU バックアップ）で、その後は BGRA（CPU バックアップ）であることが示されました。アプリ自体は色空間を設定しません。アプリ内で NV12 BT.709 に変換すると、すべてのエクスポートが同一になりました。
• タグなし SD ビデオは BT.709 として読み取られます（色は約 20 レベルまでずれます）。
• オーディオトラックがないソースは、無音のステレオ AAC トラックをエクスポートします。
• ビルドの比較は同じ条件でのみ行うこと：同じレイアウト、セッション内の同じ位置（最初のエクスポート vs 最初のエクスポート）、ウィンドウが前面にありフォーカスされていること（フォーカスされていないウィンドウは約 30% 遅くなることがあります）、同じプロファイルのコピー。
• 同じデスクトップ上の他のエージェントやチャットウィンドウがフォーカスを奪う可能性があります：クリックする前にスクリーンショットを撮影してください。
• ウィンドウを最初にクリックすると、フォーカスされるだけの場合があります。

7. 次のようにレポートする

何が実行されたか（ビルド、プロファイルコピー、レイアウト）、数値（フェーズタイム、ピークメモリ、サイズ、タグ）、合格したチェック（joy:// キー変更なし、フォルダ差分空、デコードクリーン）、検証されていないこと、そしてオーナーから必要とする唯一の判断事項を記載してください。「ビルドごとに 1 回実行」と、それがすべてである場合に述べてください。