WSL ↔ Windows

Linux 側のコマンドを Windows パスへそのまま投げない。先にホスト層を判定する。

いつ読むか

次のいずれかならこの Skill を適用する。毎回の確認質問は不要。

• cwd または対象 path が /mnt/c / /mnt/d / C:\ を含む
• git / tasklist / powershell.exe / Windows 上の CLI を作業ツリーに対して使う
• Unity CLI（unity open / unity status / unity command / Editor が死んだ・応答しない）
• 「Windows 側を操作」「WSL からホストのプロセス」などホスト横断の依頼

プロジェクトに操作用 wrapper がある場合は その wrapper が正。wrapper が無い、または wrapper が公式 CLI に委譲しているときは、下の Unity CLI 手順を使う。

ホスト判定

grep -qiE '(microsoft|wsl)' /proc/version

真なら以降は WSL。macOS / 素の Linux の手順をそのまま使わない。

Git

/mnt/c/... 配下のリポジトリに Linux git を使わない。status / fetch / pull が NTFS で数分ハングする。

GIT="/mnt/c/Program Files/Git/cmd/git.exe"
"$GIT" -C 'C:\Users\<Name>\Documents\<repo>' status -sb
"$GIT" -C 'C:\Users\<Name>\Documents\<repo>' fetch --prune origin
"$GIT" -C 'C:\Users\<Name>\Documents\<repo>' pull --ff-only

• -C には Windows パスを渡す（C:\...）。/mnt/c/... を git.exe に渡さない
• ハングしたら待たずに打ち切る。同じ Linux git を再試行しない
• 同期の工程（保全 commit / 競合 / push）は git-sync の範囲。ここは Windows 上でどの git を使うかだけ

パス

Windows プログラムへ渡す path は wslpath -w。表示・ログは echo ではなく printf '%s\n'。echo "C:\Users\..." は \U が潰れて C:sers になる。

WIN_PROJECT=$(wslpath -w /mnt/c/Users/Name/Documents/repo)
printf '%s\n' "$WIN_PROJECT"
# C:\Users\Name\Documents\repo

逆は wslpath -u 'C:\Users\Name\Documents\repo'。変数に入れた path を CLI へ渡すときは "$WIN_PROJECT" のまま。中身は正しい。壊れるのは表示だけ、とは限らないのでログ確認も printf。

実行ファイルのスタブ

/mnt/c/Users/.../AppData/Local/Microsoft/WindowsApps/*.exe は 0-byte の App Execution Alias であることが多い。command -v がこれを返しても実体ではない。

使う前に [ -s "$path" ] を確認する。空なら却下して実体を探す。where.exe <name> の結果から WindowsApps を除外する。unity doctor の check.path-duplicates が WindowsApps を first に出すのはこの症状。

Unity CLI

ここは Unity CLI（unity.exe）の話。Editor のコマンドライン引数（-batchmode / -quit / -executeMethod を Editor バイナリへ直渡し）とは別物。

インストール済み CLI のコマンド表はバイナリの --help が正。知らないサブコマンドは推測せず "$UNITY" <cmd> --help を見る。機械処理は --json。

三層

層	実体	用途
CLI	%LOCALAPPDATA%\Unity\bin\unity.exe	プロジェクトを開く、接続中 Editor に命令、batch 起動、診断
Editor	Hub 配下 Editor\Unity.exe	GUI。CLI の代用にしない。Store alias も不可
プロジェクト wrapper	リポジトリ内のスクリプト	あるなら そちらが正。生の CLI / Editor を直叩きしない

CLI は Editor に話しかけるクライアント。status は観察だけで起動しない。起動は open。

バイナリ

UNITY="/mnt/c/Users/<Name>/AppData/Local/Unity/bin/unity.exe"
[ -s "$UNITY" ] || { printf 'unity CLI missing or 0-byte stub\n'; exit 1; }

command -v unity / command -v Unity.exe を信じない。

WSL からの呼び方

WIN_PROJECT=$(wslpath -w /mnt/c/Users/<Name>/Documents/<project>)
UNITY="/mnt/c/Users/<Name>/AppData/Local/Unity/bin/unity.exe"

"$UNITY" --non-interactive --no-banner --version
"$UNITY" --non-interactive --no-banner --json editors running
"$UNITY" --non-interactive --no-banner --json status --project-path "$WIN_PROJECT"

• エージェントは --non-interactive。path は Windows 形式。/mnt/c/... を --project-path に渡さない
• cwd が /mnt/c のとき open / run の省略引数（カレントディレクトリ）に頼らない
• networkingMode=mirrored の WSL2 では 127.0.0.1 は Windows localhost と同じ。NAT のままなら Editor に届かない

観察の順番

信号を 1 本だけで断定しない。この順で取る。

powershell.exe -NoProfile -Command "Get-Process -Name Unity -ErrorAction SilentlyContinue | Select-Object Id,Path"
"$UNITY" --non-interactive --no-banner --json editors running
"$UNITY" --non-interactive --no-banner --json status --project-path "$WIN_PROJECT"

信号	見ること	見ないこと
Get-Process -Name Unity	path が Editor\Unity.exe か。Hub / CLI は除外	tasklist | grep -i unity | head（Hub で埋まる）
editors running --json	count / pid / projectPath / hasPipeline / reachable	human 表だけ見て空欄を死と断定
status --json	Pipeline に接続できたインスタンス。success と errors[].code	STATUS_NO_INSTANCES を即 DEAD / 即 pipeline install
doctor	CLI 自身の path・スタブ重複・ライセンス	Editor の生存確認

status の失敗文は「Pipeline を入れろ」と書いてあっても、起動中（reachable: false）の定番である。editors running で PID があり hasPipeline: true なら install しない。待つ。

状態 → 対処

先に状態を名前で固定してから手を動かす。状態が変わるまで同じ手を繰り返さない。

状態	観測	やる	やるな
HUB_ONLY	Hub プロセスだけ。Get-Process Unity 空。editors running count 0	DEAD と同じ。open	Hub を Editor と数える
DEAD	Editor プロセス無し。editors running count 0。status も空	"$UNITY" --non-interactive --no-banner open "$WIN_PROJECT"。その後 STARTING として待つ	command リトライ。status 失敗だけで放置。run/build で代用起動
STARTING	Editor PID あり。reachable: false。status が STATUS_NO_INSTANCES	15s 間隔で editors running --json を見る。上限 10 分。reachable: true になったら READY	二度目の open。pipeline install。command。run
READY	reachable: true。status の対象 instance が state: "ready"	list → command --timeout。read-only なら get_quality_settings / console --tail で疎通確認	GUI が居るのに run/build/-batchmode
WRONG_PROJECT	Editor は生きているが projectPath が対象と違う	対象を open。既存 Editor は確認なしに殺さない	別 project へ command して対象と錯覚
NO_PIPELINE	reachable は true 寄り、または起動完了後も hasPipeline: false	pipeline install --project-path "$WIN_PROJECT"。終わったら待つ	起動中の STATUS_NO_INSTANCES をこれと取り違える
STUCK_STARTING	STARTING が上限超過。プロセスは居るが reachable が false のまま	状況を報告。wrapper があるなら wrapper の復旧に渡す。ユーザーが殺してよいと言うまで Editor を kill しない	同じ open を連打。run で lock
LOCK	GUI が対象 project を開いているのに run/build したい	command 側	生 -batchmode
STUB_PATH	doctor の path-duplicates が WindowsApps を first	%LOCALAPPDATA%\Unity\bin\unity.exe を絶対 path で叩く	unity を PATH 任せ
CMD_TIMEOUT	command が既定 30s で落ちる	--timeout を上げて一回だけ再実行	失敗即 open

待ち方（STARTING）

# reachable になるまで待つ。status は待たない（起動中は必ず失敗する）
i=0
while [ "$i" -lt 40 ]; do
  i=$((i+1))
  out=$("$UNITY" --non-interactive --no-banner --json editors running)
  printf '%s\n' "$out"
  if printf '%s' "$out" | grep -Eq '"reachable"[[:space:]]*:[[:space:]]*true'; then
    break
  fi
  sleep 15
done

JSON の data.instances[].reachable が true になった時点で抜ける（複数 Editor が居る場合は、抜けた後に対象 projectPath の instance が reachable かを確認する）。10 分超えたら STUCK_STARTING。import / compile / domain reload 中は分単位で false のままになる。これは故障ではない。

作業セット

# DEAD → 起動。同じ project が STARTING/READY なら呼ばない
"$UNITY" --non-interactive --no-banner open "$WIN_PROJECT"

# READY になってから
"$UNITY" --non-interactive --no-banner --json list --project-path "$WIN_PROJECT"
"$UNITY" --non-interactive --no-banner command --project-path "$WIN_PROJECT" --timeout 120 -- <name> [args...]

command の第一引数を省略すると一覧になる。list / command は Pipeline が Editor 側に入り、かつ READY であること。

"$UNITY" --non-interactive --no-banner pipeline list
"$UNITY" --non-interactive --no-banner pipeline install --project-path "$WIN_PROJECT"

install は NO_PIPELINE のときだけ。

open

対象プロジェクトを ProjectVersion.txt の Editor で開く。Hub レジストリ名、glob、ファイルシステム path を受け付ける。CLI は Editor 起動を待ってブロックすることがある。バックグラウンドにして、待ちは上の STARTING ループで見る。

"$UNITY" --non-interactive --no-banner open "$WIN_PROJECT"
"$UNITY" --non-interactive --no-banner open "$WIN_PROJECT" --editor-version 6000.0.65f1

• --editor-path には Editor 本体。CLI 自身の path を渡さない
• 既に同じ project が STARTING/READY なら二重起動しない

run / build / test（ヘッドレス）

Editor を batch で spawn する。GUI が同じ project を開いていると lock する。READY なら command。閉じている／CI ならこちら。

"$UNITY" --non-interactive --no-banner run "$WIN_PROJECT" -- -nographics -quit
"$UNITY" --non-interactive --no-banner run "$WIN_PROJECT" --command <name> -- --target StandaloneWindows64
"$UNITY" --non-interactive --no-banner build "$WIN_PROJECT" --target StandaloneWindows64 --execute-method Builder.PerformBuild
"$UNITY" --non-interactive --no-banner test "$WIN_PROJECT" --mode EditMode --output "$WIN_PROJECT\\test-results.xml"

run / test の --timeout は Unity プロセスごと殺す。未指定は無効。--allow-install で Editor を入れるのは、ユーザーがインストールを依頼したときだけ。

診断

"$UNITY" --non-interactive --no-banner --json doctor
"$UNITY" --non-interactive --no-banner editors -i
"$UNITY" --non-interactive --no-banner --json env

やってはいけないこと

• Editor バイナリや Store alias を CLI の代わりに叩く
• 生きている GUI Editor に run / build / 生の -batchmode
• STATUS_NO_INSTANCES を見てすぐ pipeline install またはすぐ open
• STARTING 中に command をリトライし続ける
• wrapper があるリポジトリで生 CLI に逃げて wrapper の復旧を飛ばす
• Linux git や Linux 側の再帰コピーを /mnt/c のプロジェクトに対して走らせる

private はこの CLI に付属する MCP 入口。Editor 操作の正は CLI コマンド。MCP 経由に切り替えない。MCP スキルが別にロードされているときだけ、そのスキルに従う。

待たない

/mnt/c 上の git status・再帰コピー・全ファイル grep は完了しない前提で上限を付ける。2 分以上動かない同一コマンドは打ち切り、Windows 側ツール（git.exe / rg.exe / unity.exe）へ切り替える。同じ Linux コマンドの再試行はしない。

例外: Unity の STARTING 待ちは 10 分まで許す。これは NTFS ハングではなく import / compile 待ち。