ADS/voice-diagram-comment
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
音声図解コメントツール — 図解にテキスト選択・ピン・音声でコメントできるフィードバックツール
1 Commit 1 Branch 0 Tags 210 KiB
TypeScript 63.6%
HTML 33.8%
Shell 2.3%
JavaScript 0.3%
main
Go to file
snc 6cba1f1351 initial commit 
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-30 21:22:21 +09:00
.claude/skills initial commit 2026-07-30 21:22:21 +09:00
public initial commit 2026-07-30 21:22:21 +09:00
scripts initial commit 2026-07-30 21:22:21 +09:00
src initial commit 2026-07-30 21:22:21 +09:00
tests initial commit 2026-07-30 21:22:21 +09:00
.env.example initial commit 2026-07-30 21:22:21 +09:00
.gitignore initial commit 2026-07-30 21:22:21 +09:00
eslint.config.mjs initial commit 2026-07-30 21:22:21 +09:00
next.config.ts initial commit 2026-07-30 21:22:21 +09:00
package-lock.json initial commit 2026-07-30 21:22:21 +09:00
package.json initial commit 2026-07-30 21:22:21 +09:00
README.md initial commit 2026-07-30 21:22:21 +09:00
tsconfig.json initial commit 2026-07-30 21:22:21 +09:00
vercel.json initial commit 2026-07-30 21:22:21 +09:00
vitest.config.ts initial commit 2026-07-30 21:22:21 +09:00

README.md

音声図解コメントツール

わからない言葉やしくみを 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 を開く
  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 が無い場合は、次に「セットアップして」と伝えれば
    初期セットアップが始まる、と案内してください）
  1. 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 運営が動作確認済みです。