コンテンツにスキップ

開発環境のセットアップ

前提条件

  • Python 3.12+（バックエンドは3.11でも動作しますが、プラグインのテストは3.12で行います）。
  • Node 24+（Vite 8が必要）。古いNodeバージョンはビルドステップでcrypto.hash is not a functionというエラーで失敗します。
  • Poetry（Python依存関係管理のため）。インストール: curl -sSL https://install.python-poetry.org | python3 -
  • npm（Nodeに同梱）。
  • GNU Make（オーケストレーションターゲットのため）。MakefileはSOTであり、すべてのCIコマンドはそこに記載されています。

クローン + インストール

git clone git@github.com:astrapi69/adaptive-learner.git
cd adaptive-learner
make install

make installは以下を実行します。

  1. cd backend && poetry install — バックエンド + プラグインのパス依存関係。
  2. cd frontend && npm ci — フロントエンドの依存関係（Node 24）。
  3. plugins/内のすべてのプラグインをバックエンドのvenvにパス依存関係としてインストール（develop = trueにより編集が即時反映）。

make installが失敗する場合、最も多い原因はPoetryが誤ったPythonを選択することです。backend/（および深く入った場合は各プラグイン）でpoetry env use python3.12を実行して再インストールしてください。

設定

バックエンドは3層のチェーンから設定を読み取ります（優先度が高いものが優先されます）。

  1. 環境変数（ADAPTIVE_LEARNER_*プレフィックス付き）。
  2. ユーザーシークレット（~/.config/adaptive_learner/secrets.yaml）— 最初の起動時にコメント付きテンプレートとして自動生成（POSIXではchmod 0600が適用）; gitにはコミットされません。
  3. デフォルト（backend/config/app.yaml内）。

さらにプロバイダーごとのAIキー解決が上乗せされます: env > secrets.yaml > Fernet暗号化DBカラム（Settings UIで設定）。UserSettingsOutのkey_source_*フィールドとしてUIに公開されます。

必須のシークレットはADAPTIVE_LEARNER_SECRET_KEYです。FernetでユーザーのAPIキーを保存時に暗号化するために使用します。python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"で生成します。設定できる場所は3つあります（優先度が高いものが優先）: ADAPTIVE_LEARNER_SECRET_KEY環境変数、secrets.yamlのsecret_key:、または開発用の一時キーとしてmake dev-secret。キーが未設定の場合、アプリは起動時にハードフェイルします（サイレントデフォルト生成という落とし穴はありません）。詳細はdocs/configuration.mdを参照してください。

実行

make dev

ポート18001でバックエンドを、ポート15174でフロントエンドを並行して起動します。バックエンドはuvicornの--reloadでホットリロードに対応し、フロントエンドはViteの開発サーバーです。Ctrl-Cを一度押すと両方が停止します。

バックグラウンドモード:

make dev-bg   # バックエンド + フロントエンドをバックグラウンドで起動
make dev-down # 停止

テスト

make test                 # バックエンド + プラグイン + フロントエンドVitest
make test-backend         # バックエンドpytestのみ
make test-frontend        # フロントエンドVitestのみ
make test-coverage        # オプションのカバレッジ実行（低速）

E2Eテスト:

cd e2e && npx playwright test

v1.20.0では16個のスモークスペックファイル: ランディング、オンボーディング + アセスメント、セッション（3チャンクSSE）、カリキュラム、設定、モバイルビューポート、同期ペアリング、バックアップラウンドトリップ、マルチサイクルオートループ、インポート + 分析、MDエクスポート、サブジェクト/タグフィルター、リッチテキストノート、モデルピッカー。

リント + フォーマット

cd backend && poetry run ruff check .       # Pythonリント
cd backend && poetry run ruff format .      # Pythonフォーマット
cd frontend && npx tsc --noEmit             # TypeScriptチェック
cd frontend && npm run lint                 # ESLint
cd frontend && npm run format               # Prettier

pre-commitフックにより、すべてのコミット時にruff + フォーマッターのチェックが強制されます。

cd backend && poetry run pre-commit install

ドキュメント

make docs-install   # 一回限り、docs/にMkDocsのvenvをインストール
make docs-serve     # localhost:8000でドキュメントをホットリロードで提供
make docs-build     # 静的サイトをsite/にビルド

docsのvenvはバックエンドとは別です。MkDocsはmkdocs-material + mkdocs-static-i18nを含む独自のdocs/pyproject.tomlを持ちます。

よくある問題

  • make devが「port already in use」でクラッシュする: 別のAdaptiveLearnerインスタンスがまだ実行中です。make dev-downまたはpkill -f uvicornを実行してください。
  • 「duplicate column name」でテストが失敗する: Alembicのマイグレーションがスキーマを変更しています。backend/adaptive_learner.dbを削除して再実行してください。
  • npm run buildがNode 18で失敗する: Node 24にアップグレードしてください。Vite 8が必要です。