AI が止められた操作を「ユーザーのダブルクリック1回」に落とす手渡しスクリプトの作り方（Windows）

AI エージェントに権限ガードがあって実行できない操作（本番デプロイなど）を、ユーザーの手作業を1回だけに圧縮して渡すための型。 Windows の .cmd で確実に踏む2つの罠と、デプロイ対象が手元のリポジトリと乖離している場合の安全な反映手順をまとめる。

1. 手渡しバッチに日本語を書いてはいけない

.cmd に chcp 65001（UTF-8 化）と日本語を同居させると、cmd.exe が全行を壊して実行する。

実際に出る症状:

'ho' は、内部コマンドまたは外部コマンド、操作可能なプログラムまたはバッチ ファイルとして認識されていません。
'ause' は、内部コマンドまたは外部コマンド、…
指定されたパスが見つかりません。

echo が ho に、pause が ause になっている。行頭が1〜2文字食われている。

原因: cmd.exe はバッチファイルを1行ずつバイトオフセットで読み戻す。chcp でコードページが変わると、 既に読んだ日本語（UTF-8 のマルチバイト）のバイト数と文字数の対応がずれ、次行の読み出し位置が前方にずれる。 UTF-8 で保存したバッチに非 ASCII 文字がある限り再発する。エージェントが書くファイルは既定で UTF-8 なので必ず踏む。

対策: バッチの中身は ASCII のみ。説明文・警告・完了メッセージは全部、呼び出す側のスクリプト（Node/Python 等）の標準出力に移す。 chcp 65001 済みのコンソールなら Node の UTF-8 出力はそのまま正しく表示される。ファイル名の日本語は中身のパースに影響しないので可。

@echo off
chcp 65001 >nul
title my-task setup
set "NODE_EXE=C:\Program Files\nodejs\node.exe"
if not exist "%NODE_EXE%" set "NODE_EXE=node"
"%NODE_EXE%" "C:\path\to\task.mjs"
if errorlevel 1 echo [NG] error level %errorlevel%
echo.
pause

2. node はフルパスで呼ぶ／ログをファイルに残す

ダブルクリックで開く cmd.exe の PATH は、エージェントが使っているシェルの PATH とは別物。node が見つからず一瞬で閉じることがある。 この時ユーザーには「何も起きなかった」としか見えず、エージェント側も原因を特定できない。

• node は絶対パスを第一候補にし、無ければ PATH にフォールバックする（上記テンプレの NODE_EXE）。
• スクリプト側は冒頭で console を乗っ取り、デスクトップのログファイルにも書く。ウィンドウが一瞬で消えても証拠が残る。

const LOG = 'C:/Users/<user>/Desktop/task-log.txt';
try { fs.writeFileSync(LOG, `開始: ${new Date().toISOString()}\n`); } catch (e) {}
for (const level of ['log', 'error']) {
  const original = console[level].bind(console);
  console[level] = (...args) => {
    original(...args);
    try { fs.appendFileSync(LOG, args.join(' ') + '\n'); } catch (e) {}
  };
}

検証のコツ: 実行されたかどうかは「ユーザーの自己申告」ではなく作業フォルダやログの実在で判定する。 作業フォルダが作られていなければ、スクリプトは1行も走っていない。

3. 反映先が手元のリポジトリと乖離している前提で作る

本番（クラウド側のプロジェクト）がリポジトリより先行していることは珍しくない。 GUI エディタでの直接編集、別メンバーの手動反映、別セッションの push などで、リポジトリに一度も存在しないファイルが本番にだけある状態が普通に発生する。

この状態で「ローカルのファイル集合で本番を置き換える」型のデプロイ（clasp push、rsync --delete、terraform apply 等）を リポジトリ側から実行すると、本番専用ファイルが消え、本番が先行している変更も巻き戻る。

git 上で「このコミットは本番最終反映の子孫だから巻き戻しゼロ」と確認しても無意味。それは git 内部の比較にすぎず、本番の実体とは無関係。

安全な手順（pull-patch-push）:

1. 空のディレクトリに接続設定ファイルだけを置き、本番から pull して実体を取得する
2. 取得した実体を起点にパッチを当てる（アンカー文字列が見つからなければ中止する）
3. そこから push する
4. もう一度 pull して read-back 検証する（「反映されたはず」で終わらせない）

// 事前ガード: 想定ファイル数を下回ったら push しない（取得失敗時の全消し事故を防ぐ）
if (files.length < EXPECTED_MIN) throw new Error(`取得ファイル数が異常です (${files.length})`);

この形にしておけば何度実行しても安全（既にパッチ済みなら「追加済み」と出して終了する）ので、ユーザーにクリックをやり直してもらえる。

4. 権限ガードに止められた時の進め方

• 拒否は操作単位。一括操作が拒否されても、目的の変更だけを最小単位で1回試す価値はある。
• 言い換えて再試行しない。拒否カテゴリを1行記録して次へ進む。
• 手渡す前に「エージェント側で吸収できないか」を先に書く。手渡しは最後の手段で、残す手作業は1回だけにする。
• 手渡した後も結果はエージェントが実体で検証する。ユーザーに画面確認を依頼して終わりにしない。

よくある失敗まとめ

症状	原因	対策
'ho' は… 'ause' は…	.cmd に chcp と日本語が同居	バッチは ASCII のみ、日本語は呼び出し先の出力へ
ウィンドウが一瞬で消える	node が PATH に無い	絶対パス優先 + pause + ログファイル
「クリックした」が反映されていない	古いコピーを開いている／起動していない	作業フォルダ・ログの実在で判定し、ファイルのバイト数と更新時刻を確認する
デプロイで本番のファイルが消えた	ローカル集合で本番を置換した	pull した実体を起点にして push、push 後に再 pull で read-back