マニュアルAI

Notionの親ページと子ページを読み込み、Ollamaだけで検索・回答する、学習用のローカルRAGチャットです。

品質・安全性への取り組み

安心してローカルで利用できるよう、次の対策を実装しています。

• Node.js標準機能による自動テスト
• GitHub Actionsでテスト・ESLint・本番ビルドを自動実行
• 検索結果の並び順と件数制限をテスト
• 不正な検索データを安全に処理
• localhost以外からのAPIアクセスを拒否
• 外部Originからのアクセスを拒否
• Notion未接続・Ollama停止時のエラー表示
• 処理中のボタン連打を防止
• アクセストークンや検索データをGit管理から除外

テスト結果

• 自動テスト：7件成功
• ESLint：成功
• Next.js本番ビルド：成功

テストは次のコマンドで実行できます。

npm test

できること

• Notionの深い子ページまで再帰的に読み込む
• ページ階層と見出しを残したまま検索カードを作る
• EmbeddingGemmaで質問に近い箇所を検索する
• Qwen3で参考資料に基づく日本語回答を生成する
• 回答と一緒に参照元のNotionページを表示する
• OpenAI APIや有料ベクトルDBを使わず、Mac内で実行する

大切な制限

このリポジトリは学習用MVP・ローカル実行専用です。認証付きの社内サービスやインターネット公開用には作られていません。

• Vercel、Cloudflareなどへデプロイしないでください。
• 0.0.0.0で起動したり、LANへ公開したりしないでください。
• 個人情報・機密情報を含む本番マニュアルには、追加の認証・権限制御・監査が必要です。
• 「完全無料」はAPI課金がないという意味です。Macの電力・保存容量・通信料は含みません。

詳しくは SECURITY.md を読んでください。

しくみ

Notion
  ↓ ページと子ページを取得
Next.js
  ↓ 見出しごとに分割
EmbeddingGemma
  ↓ ベクトルをローカルJSONへ保存
類似検索
  ↓ 関連箇所だけ渡す
Qwen3
  ↓
回答＋参照元リンク

必要なもの

• macOS Sonoma 14以降を推奨
• Node.js 20以降
• Ollama
• 読み取り専用のNotion Internal Connection
• Ollamaモデルqwen3:4bとembeddinggemma

インストール

git clone <このリポジトリのURL>
cd manual-ai
npm install
ollama pull qwen3:4b
ollama pull embeddinggemma

Notionの準備

1. Notion DevelopersでInternal Connectionを作ります。
2. Read contentだけを有効にします。
3. Content accessに、検索対象の親ページを追加します。
4. Integration tokenをコピーします。GitHub、チャット、スクリーンショットには載せないでください。

起動

npm run dev

ブラウザで http://localhost:3000 を開きます。

テスト

検索順とローカルアクセス制限の自動テストを実行できます。

npm test

1. 画面左側へNotion Integration tokenを入力します。
2. 検索対象のNotionページURL、またはページIDを入力します。
3. 「接続する」を押します。
4. 「同期を開始」を押します。
5. 同期完了後、チャット欄から質問します。

Notionを更新したら「もう一度同期」を押してください。

ローカルに作られる秘密ファイル

ファイル	内容	GitHubへの登録
data/config.json	Notion tokenとページID	禁止・.gitignore済み
data/rag-index.json	マニュアル本文とベクトル	禁止・.gitignore済み
.env*	将来使う場合の環境変数	禁止・.gitignore済み

設定ファイルは所有者だけが読める権限で作成されます。アプリのAPIもlocalhost以外からのリクエストを拒否します。

開発時の確認

npm run lint
npx next build --webpack

ライセンス

MIT License