ウォークスルー
ゼロから組み立てる
空のフォルダから始めて、動作するローカル AI チャットアプリに到達する 10 ステップのウォークスルー。
このウォークスルーは LocalLens を内側から外側へと再構築します。各ステップで ファイルを 1 つ追加し(ステップ 0 はプロジェクトの土台作り)、そのファイルが 存在する理由を説明し、最小限のコードを示し、次のステップへ進みます。
順番は意図的なものです。コードベースの import 方向と一致しているので、 どのステップもまだ書いていないファイルに依存することはありません。
10 のステップ
- プロジェクトのセットアップ —
bun init、依存のインストール、設定とスクリプトの準備。 - ドメイン型と
AppError— 他のすべての ファイルが import する共有語彙。 - チャンク化と根拠付きプロンプト — まだ SDK の存在を知らない検索側のヘルパー。
- QVAC ゲートウェイ — モデル読み込み、 取り込み、検索、ストリーミング生成。
- JSON ストア — brain とチャンクを
.locallens/store.jsonに永続化。 - ファイルアダプタ — ローカルフォルダの 走査と、ブラウザのファイルピッカー入力の正規化。
- アプリケーションワークフロー —
LocalLensAppですべてを配線する。 - CLI — UI なしのエントリポイント。
- Bun サーバー — オプションの HTTP インターフェース。
- ブラウザ UI — サーバーの上に乗る薄いレイヤー。
学習に必要なところだけ
ウォークスルーはアーキテクチャを教える部分をカバーします。CSS の各 ルールや UI のヘルパーをすべて説明はしません。完全なソースは GitHub にあります。本ページを ひととおり読んだら、そちらにも目を通してください。
この順序にする理由
各ステップは、その前までに作ったものだけに依存しています。
project shell → bun init, deps, configs (no source yet)
domain.ts → no internal imports
rag.ts → imports domain
qvac.ts → imports domain
store.ts → imports domain
files.ts → imports domain
locallens.ts → imports domain, files, qvac, rag, store
cli.ts → imports domain, locallens
server.ts → imports domain, locallens
ui/ → talks to server.ts over HTTPこの順序で組み立てれば、各ステップのあとも bun run typecheck は
グリーンのままです。