既存の業務スプレッドシートに「成果物シート」を自動追加する（Drive コネクタでは不可・Sheets API 直叩き）

調べ物やリスト作成の成果を、新しいファイルではなく案件の正本スプレッドシートの中に新しいタブとして足すための手順。依頼者がそのタブに直接書き込んで運用を続けられる形にする。

なぜ新規ファイルを作らないのか

• 正本が1ファイルに集約され、関係者が同じ場所だけ見れば済む
• 案件ごとに成果物ファイルが増えないので、検索と共有権限の管理コストが案件数に比例して増えない
• 次に同種の案件が来たとき、その1ファイルを読むだけで過去の候補・単価・断られた理由まで再利用でき、外部調査のやり直しが不要になる

前提の落とし穴（ここで時間を失う）

1. Drive の MCP コネクタ／汎用 Drive API ではシートタブを追加できない。 ファイルの作成・読み書きはできても addSheet が無い。Sheets API を直接叩く必要がある。
2. Drive コネクタの create_file 系は本文を base64 で要求することがある。 プレーンテキストを渡すと The file content is not a valid base64 string. で落ちる。パラメータ名も name ではなく title 等、実装ごとに違う。エラー文のフィールド名をそのまま読んで直す。
3. 大きなスプレッドシートの読み取りは応答上限を超える。 100万字級になるとツールの戻り値がファイルに退避される。親の文脈を守るため、退避ファイルは別プロセス（スクリプト）かサブエージェントに解析させ、要点だけ受け取る。
4. Windows の Node で絶対パスを import するときは file:/// が必要。 import x from 'C:/path/mod.mjs' は ERR_UNSUPPORTED_ESM_URL_SCHEME（Received protocol 'c:'）になる。file:///C:/path/mod.mjs と書く。

手順

1. 書き込みスコープのアクセストークンを得る

既存の Drive 連携があるなら、その認証モジュールにスプレッドシート用のスコープを要求する。

import { getDriveToken } from 'file:///<絶対パス>/drive-auth.mjs';
const token = await getDriveToken({ scope: 'https://www.googleapis.com/auth/spreadsheets' });

読み取り専用スコープのトークンを使い回すと addSheet で 403 になる。スコープは明示する。

2. タブを足して値を流し込む（冪等に）

const API = 'https://sheets.googleapis.com/v4/spreadsheets';
const auth = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };
const SHEET_ID = '<スプレッドシートID>';
const TITLE = '<タブ名>';

// 既存タブを調べ、同名があれば addSheet を飛ばす（再実行しても壊れない）
const meta = await fetch(`${API}/${SHEET_ID}?fields=sheets.properties`, { headers: auth });
const exists = (await meta.json()).sheets.some((s) => s.properties.title === TITLE);

if (!exists) {
  await fetch(`${API}/${SHEET_ID}:batchUpdate`, {
    method: 'POST', headers: auth,
    body: JSON.stringify({ requests: [{ addSheet: { properties: {
      title: TITLE,
      gridProperties: { rowCount: 60, columnCount: 13, frozenRowCount: 1 },
    } } }] }),
  });
}

// rows は配列の配列。長さが揃っていなくてよい（短い行はそのまま左詰め）
await fetch(`${API}/${SHEET_ID}/values/${encodeURIComponent(`'${TITLE}'!A1`)}?valueInputOption=USER_ENTERED`, {
  method: 'PUT', headers: auth, body: JSON.stringify({ values: rows }),
});

タブ名を range に入れるときはシングルクォートで囲んでから URL エンコードする（日本語・空白・記号を含むタブ名で必須）。

3. read-back verify する（省略しない）

書き込み API が 200 を返しても、range 指定ミスで別タブに入っていることがある。書いた場所を読み返してから完了と言う。

const back = await fetch(`${API}/${SHEET_ID}/values/${encodeURIComponent(`'${TITLE}'!A1:B3`)}`, { headers: auth });
console.log('READBACK', JSON.stringify((await back.json()).values));

4. タブへ直接飛ぶ URL を渡す

const meta2 = await fetch(`${API}/${SHEET_ID}?fields=sheets.properties`, { headers: auth });
const gid = (await meta2.json()).sheets.find((s) => s.properties.title === TITLE).properties.sheetId;
// https://docs.google.com/spreadsheets/d/<ID>/edit#gid=<gid>

gid を付けないと先頭タブが開き、受け取った人が自分で探すことになる。gid まで含めて渡す。

中身の作り方（運用に効く部分）

• 記入用の空列を用意する。 候補リストなら「ステータス」「金額」「備考」を空欄で並べておく。読む人がその場で書き込めることが、別ファイルにしないことの価値そのもの。
• 不明は「不明」と書く。 推測で埋めない。後から埋める人が、未調査なのか調査済みで無いのかを区別できる。
• 末尾に前提条件を併記する。 日時・場所・規模・予算・先方担当など、そのタブ単体で判断できる情報を数行置く。元のファイルの別タブを探させない。
• 優先度を1列目に置いて並べ替え済みで渡す。 並べ替えを読む人にさせない。

実行環境での注意

• 使い捨てスクリプトは一時ディレクトリにファイルとして置き、node <file> で実行する。長いコードをシェルの引数に埋め込むと、クォート崩れと安全機構の誤検知の両方を踏む。
• 同じスクリプトを2回実行しても安全になっているか（addSheet のスキップ、PUT の上書き）を必ず確認してから走らせる。

効果

• 成果物ファイルの増殖と、そのたびの共有設定が消える
• 過去案件の再利用が「1ファイルを開く」だけになり、同種案件での外部調査をやり直さずに済む
• 受け取った人の操作が「リンクを開いて書き込む」だけになる