voice-diagram-comment/.claude/skills/setting-up-comment-tool/SKILL.md

name	description
setting-up-comment-tool	音声図解コメントツールの初期セットアップ（Vercel・Neon・Gemini APIキー）を対話的にガイドするスキル。「セットアップして」「セットアップの続きをして」「コメントツールをセットアップして」「フィードバック機能を設定して」「音声図解コメントツールを使えるようにして」と依頼された際、および「コメントが保存されません」などセットアップ起因のトラブル調査を求められた際に使用する。

Setting Up Comment Tool

図解に対するコメント機能（テキスト引用・ピン・音声）を使えるようにする初期セットアップ。Vercel（ホスティング）・Neon Postgres（データベース）・Gemini APIキー（音声解析）の設定を対話的にガイドする。

実行するのは1回だけ。 セットアップ完了後は、図解を作ってsurge.shにデプロイするだけで自動的にコメント機能が付く。

用語の定義

• ツールフォルダ: このツール本体（package.json の name が voice-diagram-comment-tool のフォルダ）。npm / vercel コマンドはすべてここで実行する
• リポジトリルート: .claude フォルダがある階層。fb-tool-url.txt / fb-api-token.txt はここに保存する（デプロイスクリプトがここから読むため）

Step 0: ツールフォルダの特定

1. ワークスペースのルートに package.json があり、name が voice-diagram-comment-tool なら、ルートがツールフォルダ（単体利用）
2. なければ、ワークスペース内から name が voice-diagram-comment-tool の package.json を探す（別リポジトリに組み込んだ利用。フォルダ名は通常 voice-diagram-comment）
3. 見つからない場合、以下を伝えて終了:

ツール本体のフォルダが見つかりません。「voice-diagram-comment」（音声図解コメントツール）フォルダがこのリポジトリ内にあるか確認してください。

前提確認

Node.js

node --version

バージョン番号が表示された → 次に進む。 command not found → .claude/skills/creating-visual-explainers/references/node-install-guide.md の手順でインストールを案内する。

Vercel CLI

vercel --version

バージョン番号が表示された → 次に進む。 command not found → 以下を実行:

npm install -g vercel

ワークフロー

以降のコマンドは、明記がない限りツールフォルダで実行する。

Step 1: 依存関係のインストール

npm install

Step 2: Vercelにログイン

vercel login

ブラウザが開く。以下を伝える:

ブラウザでVercelのログイン画面が開きます。 アカウントを持っていない場合は「Sign Up」から無料アカウントを作成してください。 メールアドレスまたはGitHubアカウントで登録できます。 ログインが完了したら、ターミナルに戻ってください。

Step 3: Vercelに初回デプロイ

先にデプロイしてVercelプロジェクトを作成する（環境変数の設定にはプロジェクトが必要なため）。

自動命名に任せると名前の衝突などで不正になることがある。最初にプロジェクト名を明示してリンクする:

vercel link --yes --project voice-diagram-comment-tool

（同名プロジェクトが既にある等でエラーになったら、voice-comment-tool-2 のように名前を変えて再実行する）

続いて本番デプロイ:

vercel --yes --prod

デプロイが完了すると以下の2つのURLが出力される。両方を控えておく:

• Inspect URL: https://vercel.com/{slug}/{project}/... 形式（Step 6 で使う）
• Production URL: https://xxx.vercel.app 形式（最終的なツールURL）

この時点では環境変数が未設定なのでツールはまだ動かない。そのまま次に進む。

Step 4: APIトークンの生成と設定

APIを保護するためのトークンを生成し、Vercelの環境変数に設定する。

openssl rand -hex 16

Windows（PowerShell）の場合:

[System.Guid]::NewGuid().ToString("N")

表示された文字列がトークン。これを環境変数として設定する:

echo "生成したトークン" | vercel env add API_TOKEN production

「生成したトークン」は実際に生成した値に置き換える。vercel env add が対話式プロンプトを出さずに値を受け取るよう、パイプで渡す。

同じトークンをリポジトリルートの fb-api-token.txt に保存する（1行、トークンのみ）。

Step 5: Gemini APIキーの設定

音声フィードバック（喋った内容をAIが聞き取って図解にピンを配置する機能）に使うAPIキーを設定する。

ユーザーに以下を案内する:

音声フィードバックには Google の Gemini というAIを使います。無料のAPIキーを発行しましょう。

1. ブラウザで https://aistudio.google.com/apikey を開く
2. Googleアカウントでログイン
3. 「APIキーを作成」（Create API key）をクリック
4. 表示されたキー（AIza... で始まる文字列）をコピー
5. コピーしたキーをこのチャット欄に貼り付けてください

無料枠の範囲で使えます。クレジットカードの登録は不要です。

キーを受け取ったら設定する:

echo "受け取ったAPIキー" | vercel env add GEMINI_API_KEY production

注意: 受け取ったAPIキーは環境変数の設定にだけ使う。ファイルに書き出したり、チャットの返答で復唱したりしない。

Step 6: データベースの追加

Step 3 の Inspect URL からデプロイID部分（末尾のランダム文字列）を削り、/stores を付けて Storage ページの直接URLを組み立てる。

例: Inspect URL が https://vercel.com/your-projects/voice-diagram-comment-tool/abc123xyz なら → https://vercel.com/your-projects/voice-diagram-comment-tool/stores

ユーザーにブラウザでの操作を案内する。以下の {StorageページURL} を組み立てたURLに置き換えて伝える:

コメントを保存するデータベースを追加します。ブラウザで以下のURLを開いてください。

{StorageページURL}

ページが開いたら、以下の操作をしてください。

1. 「Create Database」をクリック
2. 「Neon Postgres」を選択
3. プランは「Free」を選択（無料、クレジットカード不要）
4. 「Create」をクリック
5. 次の画面で:
   • 「Search Projects」からプロジェクトを選択
   • 「Custom Prefix」の欄を DATABASE に変更
   • 「Connect」をクリック

完了したら教えてください。

Step 7: 環境変数の取得とマイグレーション

vercel env pull .env.local

テーブルを作成:

npm run db:migrate

Migration complete. と表示されれば成功。

Step 8: 再デプロイ

環境変数を反映するため、もう一度デプロイする。

vercel --prod

Step 9: URLを保存する

ツールの固定URL（https://プロジェクト名.vercel.app 形式。通常は https://voice-diagram-comment-tool.vercel.app）を、リポジトリルートの fb-tool-url.txt に書き出す。URLのみを1行で保存する。

注意: vercel --prod の出力に表示されるランダム文字列入りのURL（例: https://voice-diagram-comment-tool-a1b2c3-xxx.vercel.app）は保存しない。デプロイ固有URLはVercelの保護機能により外部から読めないことがある。

保存したら、公開ページから widget.js に到達できることを確認する:

curl -s -o /dev/null -w "%{http_code}" "$(cat fb-tool-url.txt)/widget.js"

Windows（PowerShell）の場合:

(Invoke-WebRequest "$((Get-Content fb-tool-url.txt).Trim())/widget.js").StatusCode

200 ならOK。404 や 401 が返る場合は、Vercelダッシュボードのプロジェクト → Settings → Domains に表示されているドメインを確認し、そのURLで fb-tool-url.txt を保存し直して再確認する。

Step 10: 音声解析APIの通し検証

widget.js は静的ファイルなので、これだけではAPI（サーバーレス関数）が動いている保証にならない。無音の音声データを実際に /api/voice-analyze へ送り、Gemini まで通ることを確認する。

まず、16kHz・モノラル・1秒の無音WAVを生成してbase64化し、リクエストボディを組み立てる（リポジトリルートで実行）:

node -e '
const sr = 16000, dataLen = sr * 2; // 16bit mono 1秒
const b = Buffer.alloc(44 + dataLen);
b.write("RIFF", 0); b.writeUInt32LE(36 + dataLen, 4); b.write("WAVE", 8);
b.write("fmt ", 12); b.writeUInt32LE(16, 16); b.writeUInt16LE(1, 20); b.writeUInt16LE(1, 22);
b.writeUInt32LE(sr, 24); b.writeUInt32LE(sr * 2, 28); b.writeUInt16LE(2, 32); b.writeUInt16LE(16, 34);
b.write("data", 36); b.writeUInt32LE(dataLen, 40);
const body = {
  audioBase64: b.toString("base64"),
  mimeType: "audio/wav",
  targets: [{ index: 0, text: "テスト", heading: "テスト", isHeading: true }],
};
require("fs").writeFileSync("/tmp/fb-voice-check.json", JSON.stringify(body));
'

Windows（PowerShell）の場合: 上と同じ node -e スクリプトを実行し、出力先だけ $env:TEMP + "\\fb-voice-check.json" に読み替える（node -e はWindowsでも動く）。

続いて、APIトークンを付けてPOSTする:

curl -s -w "\n%{http_code}" -X POST "$(cat fb-tool-url.txt)/api/voice-analyze" \
  -H "Authorization: Bearer $(cat fb-api-token.txt)" \
  -H "Content-Type: application/json" \
  --data @/tmp/fb-voice-check.json

結果の判定:

• HTTP 200 で {"results":[]}（無音なので空配列）→ 音声解析まで通しで動いている。セットアップ成功
• HTTP 404 → APIルートがデプロイされていない。Vercelのビルド設定の問題（エラー対応の「音声の解析に失敗しました」を参照）
• Gemini エラー を含む応答 → Geminiのモデル名またはAPIキーの問題（エラー対応の「Gemini エラー (404)」を参照）
• HTTP 403 → fb-api-token.txt の値と Vercel の API_TOKEN が食い違っている。Step 4 をやり直す

Step 11: 完了報告

リポジトリルートに fb-tool-url.txt と fb-api-token.txt があることを確認し、以下を伝える:

セットアップ完了

あなたのコメントツール URL:
https://xxx.vercel.app

以降「図解を作って」と伝えるだけで、コメント機能付きの図解が公開されます。

公開した図解では、3通りの方法でフィードバックできます:
- テキストをマウスで選択してコメント
- 好きな場所にピンを刺してコメント
- マイクに向かって喋るだけ（AIが該当箇所にピンを自動配置）

APIはトークンで保護されています。図解のデプロイ時に自動で埋め込まれるため、
追加の操作は不要です。

fb-tool-url.txt / fb-api-token.txt / .env.local はGitにコミットしない（このフォルダの .gitignore で除外済み。別リポジトリに組み込んでいる場合は、そのリポジトリの .gitignore にも追加するよう案内する）。

エラー対応

エラーメッセージをそのまま見せず、何が起きていて何をすれば解決するかを平易に説明する。

• vercel: command not found → npm install -g vercel を実行
• DATABASE_URL is not set → Step 6のデータベース追加が完了しているか確認。完了していれば vercel env pull .env.local を再実行
• マイグレーション失敗 → ツールフォルダの .env.local に DATABASE_URL が含まれているか確認
• 音声フィードバックで「GEMINI_API_KEY が未設定です」 → Step 5が完了しているか vercel env ls で確認し、設定後に vercel --prod で再デプロイ
• 「音声の解析に失敗しました」 → まず /api/voice-analyze が404を返していないか確認する（curl -s -o /dev/null -w "%{http_code}" -X POST "$(cat fb-tool-url.txt)/api/voice-analyze" — 404以外＝APIは存在する）。404ならAPIルートがデプロイされていない。原因はVercelのビルド設定: vercel.json に buildCommand を直接書くとVercelがNext.jsを認識できず、APIが生成されない。ツールフォルダの vercel.json が {"framework": "nextjs"} のみで、package.json に vercel-build スクリプトがあることを確認し、vercel --prod で再デプロイする
• 「Gemini エラー (404)」 → 指定中のGeminiモデルが新規APIキーでは利用不可になっている（例: gemini-2.5-flash は新規ユーザーに提供終了）。echo "gemini-flash-latest" | vercel env add GEMINI_MODEL production で環境変数を設定し、vercel --prod で再デプロイする（ツールが最新版なら既定値が gemini-flash-latest のためこのエラーは起きない）
• 「コメントが保存されません」と相談された → 順に切り分ける: ①Step 9の到達確認（widget.js が200か）②vercel env ls で DATABASE_URL と API_TOKEN が production にあるか ③マイグレーション済みか（vercel env pull .env.local → npm run db:migrate）④環境変数を後から足した場合は vercel --prod で再デプロイしたか

依存

• ツールフォルダの package.json — 依存関係と db:migrate スクリプト
• ツールフォルダの scripts/migrate.ts — DBマイグレーションスクリプト
• .claude/skills/creating-visual-explainers/references/node-install-guide.md — Node.jsインストール手順
• .claude/skills/creating-visual-explainers/scripts/deploy-diagram.sh — fb-tool-url.txt / fb-api-token.txt の読み取り側