259 lines
15 KiB
Markdown
259 lines
15 KiB
Markdown
# 音声図解コメントツール
|
||
|
||
わからない言葉やしくみを 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 運営が動作確認済みです。 |