241 lines
10 KiB
Markdown
241 lines
10 KiB
Markdown
# 図解＋フィードバックツール
|
||
|
||
わからない言葉やしくみを AI に伝えるだけで、初めて聞く人にもわかるように噛み砕いた図解ページを自動で作り、フィードバック機能付きで公開できるツールです。
|
||
|
||
- **前提知識がなくても読める** — 専門用語は出てきた場所で必ずわかりやすく解説されます
|
||
- **文字の壁にならない** — カード・ステップ図・比較表など、目で見てわかる構成です
|
||
- **テキストを選んでコメント** — 公開した図解で、気になる箇所をマウスで選択するとコメント入力欄が出ます
|
||
- **優先度が色でわかる** — Must（赤）・Better（黄）・Want（緑）の 3 段階で重要度を伝えられます
|
||
- **セットアップは 1 回だけ** — 一度設定すれば、以降は図解を公開するたびにフィードバック機能が自動で付きます
|
||
- **無料で使える** — Vercel と Surge の無料プランだけで動きます
|
||
|
||
## しくみ
|
||
|
||
```
|
||
「○○を図解して」と AI に依頼
|
||
│
|
||
▼
|
||
AI が図解 HTML を output/ に生成
|
||
│
|
||
▼
|
||
deploy-diagram.sh が自動で実行
|
||
├─ fb-tool-url.txt から FB ツール URL を取得
|
||
├─ </body> の直前に widget.js の <script> を注入
|
||
└─ Surge にデプロイ
|
||
│
|
||
▼
|
||
公開 URL をブラウザで開く（FB 機能付き）
|
||
├─ widget.js … 画面右のサイドバー・コメント入力・ハイライト表示
|
||
└─ /api/comments … コメントの保存・取得
|
||
│
|
||
▼
|
||
Neon Postgres（無料DB）
|
||
└─ comments テーブル … コメントデータを永続化
|
||
```
|
||
|
||
## セキュリティについて
|
||
|
||
API はトークンで保護されています。セットアップ時に自動で生成・設定されるため、追加の操作は不要です。
|
||
|
||
- コメント API（`/api/comments`）とページ取得 API（`/api/fetch-page`）はトークンなしではアクセスできません
|
||
- 図解のデプロイ時に、トークンが自動で埋め込まれます
|
||
- `fb-api-token.txt` はトークンを保存するファイルです。Git にはコミットされません
|
||
|
||
## セットアップ
|
||
|
||
初回だけ必要な設定です。AI が順番に案内してくれます。
|
||
|
||
```
|
||
① Node.js を確認
|
||
↓
|
||
② Vercel CLI をインストール
|
||
↓
|
||
③ 依存関係をインストール
|
||
↓
|
||
④ Vercel にログイン
|
||
↓
|
||
⑤ API トークンを生成
|
||
↓
|
||
⑥ Vercel にデプロイ
|
||
↓
|
||
⑦ データベースを追加（ブラウザで操作）
|
||
↓
|
||
⑧ マイグレーション実行
|
||
↓
|
||
⑨ 完了（fb-tool-url.txt と fb-api-token.txt が生成される）
|
||
```
|
||
|
||
### やり方
|
||
|
||
Cursor のチャット欄で次のように伝えてください。
|
||
|
||
```
|
||
セットアップして
|
||
```
|
||
|
||
AI がステップごとに案内してくれます。
|
||
|
||
### 必要なもの
|
||
|
||
| 必要なもの | 説明 | 費用 |
|
||
|-----------|------|------|
|
||
| Node.js | パソコン上でプログラムを動かすための土台。AI が自動でインストールを案内します | 無料 |
|
||
| Vercel アカウント | フィードバックツールを動かすサーバー。メールアドレスで登録できます | 無料（Hobby プラン） |
|
||
| Neon Postgres | コメントデータを保存するデータベース。Vercel の画面から追加します | 無料 |
|
||
| Surge アカウント | 図解を公開するサービス。初回にメールアドレスとパスワードで登録します | 無料 |
|
||
|
||
クレジットカードの登録は不要です。
|
||
|
||
## 使い方
|
||
|
||
### 図解を作る
|
||
|
||
Cursor のチャット欄に、知りたいことを書いて送信します。
|
||
|
||
```
|
||
APIについて図解して
|
||
```
|
||
|
||
AI が図解を作り、フィードバック機能付きで自動デプロイします。
|
||
|
||
### コメントを付ける
|
||
|
||
```
|
||
① 図解ページで気になるテキストをマウスで選択
|
||
↓
|
||
② ポップアップが表示される
|
||
↓
|
||
③ 優先度を選ぶ（Must / Better / Want）
|
||
↓
|
||
④ コメントを入力して「送信」
|
||
```
|
||
|
||
初回だけ名前の入力を求められます（次回以降は自動で記憶されます）。
|
||
|
||
### 優先度の意味
|
||
|
||
| 優先度 | 色 | 使いどころ |
|
||
|--------|-----|-----------|
|
||
| Must | 赤 | 必ず直すべき箇所（事実の間違い、重大なわかりにくさ） |
|
||
| Better | 黄 | 直すとよくなる箇所（表現の改善、構成の入れ替え） |
|
||
| Want | 緑 | 余裕があれば対応（細かい表現、好みの範囲） |
|
||
|
||
### コメントを確認する
|
||
|
||
画面右端の小さなボタンをクリックすると、サイドバーが開きます。
|
||
|
||
- **未解決 / 解決済 / すべて** のフィルタで絞り込めます
|
||
- コメントカードをクリックすると、本文の該当箇所にジャンプします
|
||
- 本文のハイライトをクリックすると、サイドバーの対応カードにジャンプします
|
||
|
||
### コメントを管理する
|
||
|
||
| 操作 | できること |
|
||
|------|-----------|
|
||
| 返信 | コメントにスレッド形式で返信 |
|
||
| 解決 | 対応済みのコメントを解決済みにする（再開もできます） |
|
||
| 編集 | 自分のコメントの内容・優先度を変更 |
|
||
| 削除 | 自分のコメントを削除 |
|
||
| 優先度変更 | 自分のコメントのバッジをクリックで Must → Better → Want を切り替え |
|
||
|
||
### コメントをダウンロードする
|
||
|
||
サイドバーのヘッダーにあるボタンでエクスポートできます。
|
||
|
||
- **JSON** — プログラムで処理したいとき
|
||
- **MD** — Markdown 形式。優先度ごとに分類されて出力されます
|
||
|
||
### 図解の削除
|
||
|
||
チャット欄で「この図解を削除して」と伝えてください。AI がデプロイ履歴から URL を特定し、削除を実行します。
|
||
|
||
## 以前の図解ツールとの違い
|
||
|
||
以前は「図解ツール」と「フィードバックツール」が別々のフォルダでした。
|
||
|
||
| | 旧（別々のツール） | 新（このツール） |
|
||
|---|---|---|
|
||
| フォルダ | 図解ツール + fb-tool-v2 の 2 つ | 図解コメントツールの 1 つだけ |
|
||
| FB 機能 | 図解ツールの base.html に手動で widget を埋め込み | デプロイ時に自動注入（base.html はクリーン） |
|
||
| 再 DL 時 | base.html が上書きされて widget 設定が消える | fb-tool-url.txt で管理。base.html に影響なし |
|
||
| セットアップ | 図解ツール側で base.html を編集する手順が必要 | 「セットアップして」だけで完了 |
|
||
|
||
旧図解ツールをすでに使っている場合は、このフォルダに切り替えるだけで移行できます。`output/` 内の既存の図解はそのまま使えます（再デプロイすれば FB 機能が自動で付きます）。
|
||
|
||
## フォルダの中身
|
||
|
||
```
|
||
図解コメントツール/
|
||
├── .claude/skills/
|
||
│ ├── creating-visual-explainers/ ← 図解生成スキル
|
||
│ │ ├── SKILL.md
|
||
│ │ ├── references/
|
||
│ │ │ ├── base.html ← 図解テンプレート（widget なし）
|
||
│ │ │ ├── model-answer.html ← 模範回答
|
||
│ │ │ └── node-install-guide.md
|
||
│ │ └── scripts/
|
||
│ │ └── deploy-diagram.sh ← デプロイ＋widget 注入
|
||
│ └── setup-fb-tool/ ← セットアップスキル
|
||
│ ├── SKILL.md
|
||
│ └── references/
|
||
│ └── node-install-guide.md
|
||
├── output/ ← 図解の保存先
|
||
├── public/
|
||
│ └── widget.js ← フィードバック UI 本体
|
||
├── src/
|
||
│ ├── app/api/comments/ ← コメント CRUD API
|
||
│ └── lib/
|
||
│ ├── db.ts ← データベース接続
|
||
│ └── types.ts ← 型定義
|
||
├── scripts/
|
||
│ └── migrate.ts ← DB テーブル作成
|
||
├── fb-tool-url.txt ← セットアップ完了後に生成
|
||
├── fb-api-token.txt ← API トークン（セットアップ完了後に生成）
|
||
├── deploy-history.log ← 図解デプロイ履歴
|
||
├── package.json
|
||
└── README.md ← この説明書
|
||
```
|
||
|
||
| ファイル / フォルダ | 説明 | 触る必要 |
|
||
|---|---|---|
|
||
| `output/` | 図解の保存先 | 見るだけ |
|
||
| `public/widget.js` | フィードバック UI 本体 | なし |
|
||
| `src/app/api/comments/` | コメントの CRUD API | なし |
|
||
| `scripts/migrate.ts` | DB テーブル作成スクリプト（セットアップ時に 1 回だけ実行） | なし |
|
||
| `fb-tool-url.txt` | FB ツールの URL（セットアップ完了後に自動生成） | なし |
|
||
| `fb-api-token.txt` | API トークン（セットアップ完了後に自動生成） | なし |
|
||
| `deploy-history.log` | 図解の公開履歴（自動生成） | なし |
|
||
|
||
あなたが直接触る必要があるファイルはありません。
|
||
セットアップも図解の作成も、AI がすべて案内してくれます。
|
||
|
||
## 困ったとき
|
||
|
||
### 「セットアップして」と言っても反応しない
|
||
|
||
このフォルダ（`図解コメントツール`）を Cursor で開いているか確認してください。
|
||
フォルダの中の個別ファイルではなく、フォルダごと開く必要があります。
|
||
|
||
### Vercel へのデプロイが失敗する
|
||
|
||
チャット欄で「デプロイが失敗しました」と伝えてください。AI がエラーの内容を読み取り、対処法を案内してくれます。
|
||
|
||
### コメントが保存されない
|
||
|
||
データベースのセットアップが完了しているか確認してください。
|
||
チャット欄で「コメントが保存されません」と伝えると、AI が原因を調べてくれます。
|
||
|
||
### フィードバック欄が図解に表示されない
|
||
|
||
セットアップが完了していれば、新しく作る図解には自動で付きます。
|
||
すでに公開済みの図解には反映されないので、再デプロイしてください。
|
||
|
||
### その他のトラブル
|
||
|
||
何が起きても、まずはチャット欄で AI に状況を伝えてください。
|
||
AI がエラーの内容を読み取り、次にやるべきことを教えてくれます。
|
||
|
||
---
|
||
|
||
Mac / Windows どちらでも使えます。AI-Driven School 運営が動作確認済みです。
|