# 音声図解コメントツール

わからない言葉やしくみを AI に伝えるだけで、噛み砕いた図解ページを自動で作って公開できるツールです。公開した図解には、見た人がコメントを付けられます。コメントの付け方は3通りあります。

- **テキストを選んでコメント** — 気になる箇所をマウスで選択すると、引用付きでコメントできます
- **ピンを刺してコメント** — 図の好きな場所をクリックしてピンを立て、コメントできます
- **マイクに向かって喋るだけ** — 「上の説明はもっとシンプルに。真ん中の図は矢印が逆」と喋ると、AI（Gemini）が聞き取って、図解の該当箇所にピンを自動で配置します

さらに、こんな特徴があります。

- **優先度が色でわかる** — Must（赤）・Better（黄）・Want（緑）の3段階で重要度を伝えられます
- **セットアップは1回だけ** — 一度設定すれば、以降は図解を公開するたびにコメント機能が自動で付きます
- **無料で使える** — Vercel・Neon・Surge・Gemini API のすべて無料プランで動きます。クレジットカードの登録は不要です

## しくみ

このツールは2つの部品でできています。

```
  「○○を図解して」と AI に依頼
    │
    ▼
  ① 図解 HTML（output/ に生成 → Surge に公開される静的ページ）
    │   デプロイ時に </body> の直前へ1行だけ自動注入される
    │   <script src="{あなたのツールURL}/widget.js" data-token="xxx"></script>
    ▼
  ② バックエンド（あなたの Vercel で常時動く Next.js アプリ）＝ このフォルダ
    ├─ widget.js          … コメント UI 本体（画面右端に出るパネル）
    ├─ /api/comments      … コメントの保存・取得・更新・削除
    └─ /api/voice-analyze … 音声を Gemini に渡してピン配置情報に変換
                                  │
                                  ▼
                          Neon Postgres（comments テーブル）
```

②は1つ動いていればOKです。図解を作るたびに何かをセットアップする必要はありません。

## セットアップ

初回だけ必要な設定です。AI が順番に案内してくれます。

```
  ① Node.js / Vercel CLI を確認
        ↓
  ② Vercel にログイン・デプロイ
        ↓
  ③ API トークンを自動生成
        ↓
  ④ Gemini API キーを発行（音声機能用・ブラウザで操作）
        ↓
  ⑤ データベースを追加（ブラウザで操作）
        ↓
  ⑥ マイグレーション実行・再デプロイ
        ↓
  ⑦ 完了（fb-tool-url.txt と fb-api-token.txt が生成される）
```



### やり方

このフォルダを Cursor で開き、チャット欄で次のように伝えてください。

```
セットアップして
```

AI がステップごとに案内してくれます。

### 必要なもの


| 必要なもの         | 説明                                       | 費用            |
| ------------- | ---------------------------------------- | ------------- |
| Node.js       | パソコン上でプログラムを動かすための土台。AI が自動でインストールを案内します | 無料            |
| Vercel アカウント  | コメント機能を動かすサーバー。メールアドレスで登録できます            | 無料（Hobby プラン） |
| Neon Postgres | コメントデータを保存するデータベース。Vercel の画面から追加します     | 無料            |
| Google アカウント  | 音声を聞き取る AI（Gemini）の API キー発行に使います        | 無料            |
| Surge アカウント   | 図解を公開するサービス。初回にメールアドレスとパスワードで登録します       | 無料            |

アカウントを持っていなくても大丈夫です。セットアップの途中で AI が「今このアカウントを作ってください」と、必要になったタイミングで案内します。

### Gemini API キーの発行手順（音声機能に必要）

API キーとは、AI サービスを利用するための「あなた専用の合鍵」です。発行したことがなくても、以下の4ステップ・3分程度で作れます。セットアップ中に AI がこの手順を案内するので、事前にやっておく必要はありません。

1. ブラウザで [Google AI Studio](https://aistudio.google.com/apikey) を開く
2. Google アカウントでログインする
3. 「API キーを作成」（Create API key）ボタンを押す
4. 表示された `AIza...` で始まる文字列がキーです。セットアップ中に AI から求められたら、チャット欄に貼り付けてください

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

### 大事な注意

- **API キーやトークンは自分専用です。** 他の人と共有したり、チャットや SNS に貼ったりしないでください
- セットアップで生成される `fb-tool-url.txt`・`fb-api-token.txt`・`.env.local` は Git にコミットされない設定になっています（`.gitignore` で除外済み）
- 図解は URL を知っていれば誰でも見られます。**機密情報を図解に載せない**前提で使ってください



## 使い方



### 図解を作る

Cursor のチャット欄に、知りたいことを書いて送信します。

```
APIについて図解して
```

AI が図解を作り、コメント機能付きで自動デプロイします。

### コメントを付ける（見る側）

公開された図解を開くと、画面右端にボタンが出ます。ボタンには3つの機能が並んでいます。


| アイコン | 機能                   |
| ---- | -------------------- |
| パネル  | サイドバーの開閉。コメント一覧を見る   |
| ピン   | フィードバックモードの ON / OFF |
| マイク  | 音声フィードバックの録音開始 / 停止  |


**音声で伝える**: マイクアイコンを押して喋り、もう一度押して停止します。数秒後、AI が「どの見出しへの指摘か」を判定して、該当箇所にピンを自動で配置します。初回はブラウザがマイクの使用許可を求めるので「許可」を選んでください。

**ピンで伝える**: ピンアイコンで フィードバックモードを ON にすると、クリックでピン、ドラッグでテキスト引用コメントになります。`Esc` でモードを抜けます。

初回だけ名前の入力を求められます（次回以降は自動で記憶されます）。

### 優先度の意味


| 優先度    | 色   | 使いどころ                      |
| ------ | --- | -------------------------- |
| Must   | 赤   | 必ず直すべき箇所（事実の間違い、重大なわかりにくさ） |
| Better | 黄   | 直すとよくなる箇所（表現の改善、構成の入れ替え）   |
| Want   | 緑   | 余裕があれば対応（細かい表現、好みの範囲）      |




### コメントを確認・管理する

画面右端のパネルボタンでサイドバーが開きます。

- **未解決 / 解決済 / すべて** のフィルタで絞り込めます
- コメントカードと本文の該当箇所は相互にジャンプできます
- 返信・解決・編集・削除・優先度変更ができます
- サイドバーのボタンから **JSON / Markdown** でエクスポートできます



### 図解の削除

チャット欄で「この図解を削除して」と伝えてください。AI がデプロイ履歴（`deploy-history.log`。公開のたびに自動で記録されます）から URL を特定し、削除を実行します。

## 普段使っているリポジトリに組み込む

このフォルダを単体で使うだけでなく、**普段開発しているリポジトリの中にこのツールを入れて使う**ことができます。ファイルを手で動かす必要はありません。組み込み作業は AI に任せます。

### 手順

1. このツールのフォルダ（`voice-diagram-comment`）を、パソコンの好きな場所に置きます（クローンまたはダウンロード。すでにあるならそのままでOK）
2. 組み込みたいリポジトリを Cursor で開きます
3. 下のプロンプトをチャット欄に貼り付け、**1行目のパスだけ自分の環境に書き換えて**送信します

```
「音声図解コメントツール」をこのリポジトリに組み込んでください。

ツールの場所: （ここにフォルダのパスを書く。
  Mac の例: /Users/あなたの名前/Downloads/voice-diagram-comment
  Windows の例: C:\Users\あなたの名前\Downloads\voice-diagram-comment）

やってほしいこと:
1. 上記フォルダを、このリポジトリ内の tools/voice-diagram-comment/ にコピーする
   （node_modules・.next・.vercel・.env.local はコピーしない。.env.example はコピーしてよい）
2. コピーしたフォルダ内の .claude/skills/ にある2つのスキルフォルダを、
   このリポジトリ直下の .claude/skills/ に移動する
   （スキルはリポジトリのルートにないと Cursor に認識されないため）
3. このリポジトリの .gitignore に、トークンファイルと生成物の除外設定を追加する
   （除外すべきものは、コピーしたフォルダ内の .gitignore に書いてある。
    パスは実際の配置に合わせて調整する）
4. コピー元のフォルダ直下に fb-tool-url.txt と fb-api-token.txt があれば、
   このリポジトリのルートにコピーする（セットアップ済み環境の引き継ぎ）
5. 終わったら、組み込んだ内容と「次に何をすればいいか」を教えてください
   （fb-tool-url.txt が無い場合は、次に「セットアップして」と伝えれば
    初期セットアップが始まる、と案内してください）
```

4. AI の作業が終わったら、案内に従って「セットアップして」と伝えます（すでに単体でセットアップ済みの場合は不要です。Vercel の再デプロイも不要です）

### 組み込むとこうなる

```
  あなたのリポジトリ/
  ├── src/ ...                          ← 既存のファイルはそのまま
  ├── .claude/skills/                   ← スキルはルートに置かれる
  │   ├── setting-up-comment-tool/
  │   └── creating-visual-explainers/
  ├── tools/
  │   └── voice-diagram-comment/       ← ツール本体
  ├── output/                           ← 図解の生成先（自動作成）
  ├── fb-tool-url.txt                   ← セットアップで生成
  └── fb-api-token.txt                  ← セットアップで生成
```

以降は、そのリポジトリのチャット欄で「図解を作って」と伝えるだけで、コメント機能付きの図解が公開できます。

## フォルダの中身

```
voice-diagram-comment/
├── .claude/skills/
│   ├── creating-visual-explainers/  ← 図解生成スキル
│   │   ├── SKILL.md
│   │   ├── references/              ← 図解テンプレート・模範回答・Nodeインストールガイド
│   │   └── scripts/
│   │       └── deploy-diagram.sh    ← デプロイ＋widget 自動注入
│   └── setting-up-comment-tool/     ← セットアップスキル
│       └── SKILL.md
├── output/                          ← 図解の保存先
├── public/
│   ├── widget.js                    ← コメント UI 本体（ビルド成果物）
│   └── feedback-demo.html           ← ローカル動作確認用デモ
├── src/
│   ├── app/api/comments/            ← コメント CRUD API
│   ├── app/api/voice-analyze/       ← 音声解析 API（Gemini）
│   └── lib/ shared/ widget/         ← DB接続・共通処理・コメント UI のソースコード
├── tests/                           ← 自動テスト
├── scripts/
│   └── migrate.ts                   ← DB テーブル作成（セットアップ時に1回だけ実行）
├── .env.example                     ← 環境変数のテンプレート（実際の値は書かない）
├── package.json
└── README.md                        ← この説明書
```

セットアップ完了後に `fb-tool-url.txt`（ツールの URL）と `fb-api-token.txt`（API トークン）がリポジトリのルートに自動生成されます。あなたが手で編集する必要のあるファイルはありません。

## 困ったとき


| 症状                            | 原因と対処                                                                                          |
| ----------------------------- | ---------------------------------------------------------------------------------------------- |
| 「セットアップして」と言っても反応しない          | スキルが認識されていません。このフォルダ自体（または組み込み先リポジトリのルート）を Cursor で開いているか、`.claude/skills/` がルート直下にあるか確認してください |
| マイクを押すと「マイクへのアクセスが許可されませんでした」 | ブラウザのマイク権限を確認。`https://` のページでないと許可されません（Surge の URL は https なので通常OK）                          |
| 音声で「ピンを置ける要素が見つかりませんでした」      | 図解 HTML に見出しがありません。このツールのスキルで作った図解なら自動で入ります                                                    |
| 音声で「GEMINI_API_KEY が未設定です」    | Gemini API キーの設定が漏れています。チャット欄で「セットアップの続きをして」と伝えてください                                           |
| コメントが保存されない                   | データベースの設定が未完了の可能性。チャット欄で「コメントが保存されません」と伝えると AI が原因を調べます                                        |
| 公開済みの図解にコメント機能が付かない           | コメント機能はデプロイ時に注入されます。「この図解を再デプロイして」と伝えてください                                                     |
| その他                           | 何が起きても、まずはチャット欄で AI に状況を伝えてください。エラーの内容を読み取って、次にやるべきことを案内してくれます                                 |


---

Mac / Windows どちらでも使えます。AI-Driven School 運営が動作確認済みです。