295 lines
14 KiB
Markdown
295 lines
14 KiB
Markdown
---
|
||
name: setting-up-comment-tool
|
||
description: 音声図解コメントツールの初期セットアップ（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
|
||
|
||
```bash
|
||
node --version
|
||
```
|
||
|
||
バージョン番号が表示された → 次に進む。
|
||
`command not found` → `.claude/skills/creating-visual-explainers/references/node-install-guide.md` の手順でインストールを案内する。
|
||
|
||
### Vercel CLI
|
||
|
||
```bash
|
||
vercel --version
|
||
```
|
||
|
||
バージョン番号が表示された → 次に進む。
|
||
`command not found` → 以下を実行:
|
||
|
||
```bash
|
||
npm install -g vercel
|
||
```
|
||
|
||
## ワークフロー
|
||
|
||
以降のコマンドは、明記がない限り**ツールフォルダで実行する**。
|
||
|
||
### Step 1: 依存関係のインストール
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### Step 2: Vercelにログイン
|
||
|
||
```bash
|
||
vercel login
|
||
```
|
||
|
||
ブラウザが開く。以下を伝える:
|
||
|
||
> ブラウザでVercelのログイン画面が開きます。
|
||
> アカウントを持っていない場合は「Sign Up」から無料アカウントを作成してください。
|
||
> メールアドレスまたはGitHubアカウントで登録できます。
|
||
> ログインが完了したら、ターミナルに戻ってください。
|
||
|
||
### Step 3: Vercelに初回デプロイ
|
||
|
||
先にデプロイしてVercelプロジェクトを作成する（環境変数の設定にはプロジェクトが必要なため）。
|
||
|
||
自動命名に任せると名前の衝突などで不正になることがある。最初にプロジェクト名を明示してリンクする:
|
||
|
||
```bash
|
||
vercel link --yes --project voice-diagram-comment-tool
|
||
```
|
||
|
||
（同名プロジェクトが既にある等でエラーになったら、`voice-comment-tool-2` のように名前を変えて再実行する）
|
||
|
||
続いて本番デプロイ:
|
||
|
||
```bash
|
||
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の環境変数に設定する。
|
||
|
||
```bash
|
||
openssl rand -hex 16
|
||
```
|
||
|
||
**Windows（PowerShell）の場合:**
|
||
|
||
```powershell
|
||
[System.Guid]::NewGuid().ToString("N")
|
||
```
|
||
|
||
表示された文字列がトークン。これを環境変数として設定する:
|
||
|
||
```bash
|
||
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. コピーしたキーをこのチャット欄に貼り付けてください
|
||
>
|
||
> 無料枠の範囲で使えます。クレジットカードの登録は不要です。
|
||
|
||
キーを受け取ったら設定する:
|
||
|
||
```bash
|
||
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: 環境変数の取得とマイグレーション
|
||
|
||
```bash
|
||
vercel env pull .env.local
|
||
```
|
||
|
||
テーブルを作成:
|
||
|
||
```bash
|
||
npm run db:migrate
|
||
```
|
||
|
||
`Migration complete.` と表示されれば成功。
|
||
|
||
### Step 8: 再デプロイ
|
||
|
||
環境変数を反映するため、もう一度デプロイする。
|
||
|
||
```bash
|
||
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 に到達できることを確認する:
|
||
|
||
```bash
|
||
curl -s -o /dev/null -w "%{http_code}" "$(cat fb-tool-url.txt)/widget.js"
|
||
```
|
||
|
||
**Windows（PowerShell）の場合:**
|
||
|
||
```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化し、リクエストボディを組み立てる（**リポジトリルート**で実行）:
|
||
|
||
```bash
|
||
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する:
|
||
|
||
```bash
|
||
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` の読み取り側
|